wasm/execution/runtime_structure/

store.rs

use alloc::{borrow::ToOwned, collections::btree_map::BTreeMap, string::String, vec, vec::Vec};
use core::convert::Infallible;

use crate::{
    core::{
        decoding::{
            modules::code_section::decode_locals,
            reader::{span::Span, WasmDecoder},
        },
        structure::{
            import_subtyping::ImportSubTypeRelation,
            modules::{
                data_segments::{DataMode, DataModeActive, DataSegment},
                element_segments::{ActiveElem, ElemItems, ElemMode, ElemType},
                exports::ExportDesc,
                indices::{ElemIdx, IdxVec, TypeIdx},
            },
        },
        utils::ToUsizeExt,
    },
    execution::{
        assert_validated::UnwrapValidatedExt,
        instructions::{
            self, const_interpreter_loop::run_const_span, data_drop, elem_drop, memory_init,
            table_init, InterpreterLoopOutcome,
        },
        runtime_structure::{
            data_instances::DataInst,
            element_instances::ElemInst,
            external_values::ExternFilterable,
            function_instances::{FuncInst, HostFuncInst, WasmFuncInst},
            global_instances::GlobalInst,
            memory_instances::{linear_memory::LinearMemory, MemInst},
            module_instances::ModuleInst,
            table_instances::TableInst,
            value_stack::Stack,
        },
    },
    AddrVec, Config, DataAddr, ElemAddr, ExternVal, FuncAddr, FuncType, GlobalAddr, GlobalType,
    HostCall, HostResumable, MemAddr, MemType, Module, ModuleAddr, Ref, RefType, Resumable,
    RunState, RuntimeError, TableAddr, TableType, Value, WasmResumable,
};

/// The store represents all global state that can be manipulated by WebAssembly programs. It
/// consists of the runtime representation of all instances of functions, tables, memories, and
/// globals, element segments, and data segments that have been allocated during the life time of
/// the abstract machine.
/// <https://webassembly.github.io/spec/core/exec/runtime.html#store>
///
/// # Safety
///
/// All addresses contained in a store must be valid for their associated
/// address vectors in the same store.
pub struct Store<'b, T: Config> {
    /// The actual inner Wasm store.
    ///
    /// This is stored as a separate inner type, so that we can partially borrow a [`StoreInner`]
    /// and other fields of [`Store`] at the same time.
    pub(crate) inner: StoreInner,

    // fields outside of the spec but are convenient are below
    /// An address space of modules instantiated within the context of this [`Store`].
    ///
    /// Although the WebAssembly Specification 2.0 does not specify module instances
    /// to be part of the [`Store`], in reality they can be managed very similar to
    /// other instance types. Therefore, we extend the [`Store`] by a module address
    /// space along with a `ModuleAddr` index type.
    pub(crate) modules: AddrVec<ModuleAddr, ModuleInst<'b>>,

    pub user_data: T,
}

/// This is a Wasm store as defined by the specification. It contains all state relevant for
/// execution.
///
/// There is a directly one-to-one relation between [`Store`] and [`StoreInner`].
///
/// See: WebAssembly Specification 2.0 - 4.2.3 - Store
///
/// # Safety
///
/// All addresses contained in a [`Store`] and its [`StoreInner`] must be valid for their associated
/// address vectors in the same store.
pub(crate) struct StoreInner {
    pub(crate) functions: AddrVec<FuncAddr, FuncInst>,
    pub(crate) tables: AddrVec<TableAddr, TableInst>,
    pub(crate) memories: AddrVec<MemAddr, MemInst>,
    pub(crate) globals: AddrVec<GlobalAddr, GlobalInst>,
    pub(crate) elements: AddrVec<ElemAddr, ElemInst>,
    pub(crate) data: AddrVec<DataAddr, DataInst>,
}

impl<'b, T: Config> Store<'b, T> {
    /// Creates a new empty store with some user data
    ///
    /// See: WebAssembly Specification 2.0 - 7.1.4 - store_init
    pub fn new(user_data: T) -> Self {
        // 1. Return the empty store.
        // For us the store is empty except for the user data, which we do not have control over.
        Self {
            inner: StoreInner {
                functions: AddrVec::default(),
                tables: AddrVec::default(),
                memories: AddrVec::default(),
                globals: AddrVec::default(),
                elements: AddrVec::default(),
                data: AddrVec::default(),
            },
            modules: AddrVec::default(),
            user_data,
        }
    }

    /// Instantiate a new module instance from a [`Module`] in this [`Store`].
    ///
    /// Note that if this returns an `Err(_)`, the store might be left in an ill-defined state. This might cause further
    /// operations to have unexpected results.
    ///
    /// See: WebAssembly Specification 2.0 - 7.1.5 - module_instantiate
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that any address values contained in the
    /// [`ExternVal`]s came from the current [`Store`] object.
    pub unsafe fn module_instantiate(
        &mut self,
        validation_info: &Module<'b>,
        extern_vals: Vec<ExternVal>,
        maybe_fuel: Option<u64>,
    ) -> Result<InstantiationOutcome, RuntimeError> {
        // instantiation: step 1
        // The module is guaranteed to be valid, because only validation can
        // produce `Module`s.

        // instantiation: step 3
        if validation_info.imports.len() != extern_vals.len() {
            return Err(RuntimeError::ExternValsLenMismatch);
        }

        // instantiation: step 4
        let imports_as_extern_types = validation_info.imports.iter().map(|import| {
            // SAFETY: `import` is part of the same `validation_info` and
            // therefore it was created as part of the same `validation_info`.
            unsafe { import.desc.extern_type(validation_info) }
        });
        for (extern_val, import_as_extern_type) in extern_vals.iter().zip(imports_as_extern_types) {
            // instantiation: step 4a
            // check that extern_val is valid in this Store, which should be guaranteed by the caller through a safety constraint in the future.
            // TODO document this instantiation step properly

            // instantiation: step 4b
            let extern_type = extern_val.extern_type(self);

            // instantiation: step 4c
            if !extern_type.is_subtype_of(&import_as_extern_type) {
                return Err(RuntimeError::InvalidImportType);
            }
        }

        // instantiation: step 5
        // module_inst_init is unfortunately circularly defined from parts of module_inst that would be defined in step 11, which uses module_inst_init again implicitly.
        // therefore I am mimicking the reference interpreter code here, I will allocate functions in the store in this step instead of step 11.
        // https://github.com/WebAssembly/spec/blob/8d6792e3d6709e8d3e90828f9c8468253287f7ed/interpreter/exec/eval.ml#L789
        let module_inst = ModuleInst {
            types: validation_info.types.clone(),
            func_addrs: IdxVec::default(),
            table_addrs: IdxVec::default(),
            mem_addrs: IdxVec::default(),
            // TODO This is weird hack with soundness holes.  Wasm defines a
            // special `moduleinst_init`. Here, we want to use the `IdxVec` type
            // safety, but at the same time only the imports can be populated at
            // this point.
            global_addrs: IdxVec::new(extern_vals.iter().globals().collect())
                .expect(
                    "that the number of imports and therefore also the number of imported globals is <= u32::MAX",
                ),
            elem_addrs: IdxVec::default(),
            data_addrs: IdxVec::default(),
            exports: BTreeMap::new(),
            wasm_bytecode: validation_info.wasm,
            sidetable: validation_info.sidetable.clone(),
        };
        let module_addr = self.modules.insert(module_inst);

        let imported_functions = extern_vals.iter().funcs();
        let local_func_addrs = validation_info
            .functions
            .iter_local_definitions()
            .zip(validation_info.func_blocks_stps.iter())
            .map(|(ty_idx, (span, stp))| {
                // SAFETY: The module address is valid for the current store,
                // because it was just created and the type index is valid for
                // that same module because it came from that module's
                // `Module`.
                unsafe { self.alloc_func((*ty_idx, (*span, *stp)), module_addr) }
            });

        let func_addrs = validation_info
            .functions
            .map(imported_functions.collect(), local_func_addrs.collect())
            .expect(
                "that the numbers of imported and local functions always \
                match the respective numbers in the validation info. Step 3 and 4 \
                check if the number of imported functions is correct and the number \
                of local functions is a direct one-to-one mapping of \
                `validation_info.func_blocks_stps`",
            )
            .into_inner();

        // SAFETY: The module with this module address was just inserted into
        // this `AddrVec`
        let module_inst = unsafe { self.modules.get_mut(module_addr) };
        module_inst.func_addrs = func_addrs;

        // instantiation: this roughly matches step 6,7,8
        // validation guarantees these will evaluate without errors.
        let local_globals_init_vals: Vec<Value> = validation_info
            .globals
            .iter_local_definitions()
            .map(|global| {
                // SAFETY: All requirements are met:
                // 1. Validation guarantees that the constant expression for
                //    this global is valid.
                // 2. The module with this module address was just inserted into
                //    this store's `AddrVec`.
                let const_expr_result = unsafe {
                    run_const_span(validation_info.wasm, &global.init_expr, module_addr, self)
                };
                const_expr_result.transpose().unwrap_validated()
            })
            .collect::<Result<Vec<Value>, _>>()?;

        // instantiation: this roughly matches step 9,10 and performs allocation
        // step 6,12 already
        let elem_addrs: IdxVec<ElemIdx, ElemAddr> = validation_info.elements.map(|elem| {
            let refs = match &elem.init {
                // shortcut of evaluation of "ref.func <func_idx>; end;"
                // validation guarantees corresponding func_idx's existence
                ElemItems::RefFuncs(ref_funcs) => {
                    ref_funcs
                        .iter()
                        .map(|func_idx| {
                            // SAFETY: The module with this module address was
                            // just inserted into this `AddrVec`
                            let module = unsafe { self.modules.get(module_addr) };
                            // SAFETY: Both the function index and the module
                            // instance's `func_addrs` come from the same
                            // `Module`, i.e. the one passed into this
                            // function.
                            let func_addr = unsafe { module.func_addrs.get(*func_idx) };

                            Ref::Func(*func_addr)
                        })
                        .collect()
                }
                ElemItems::Exprs(_, exprs) => exprs
                    .iter()
                    .map(|expr| {
                        // SAFETY: All requirements are met:
                        // 1. Validation guarantees that all constant expressions
                        //    for elements, including this one, are valid.
                        // 2. The module with this module address was just inserted into
                        //    this store's `AddrVec`.
                        let const_expr_result = unsafe {
                            run_const_span(validation_info.wasm, expr, module_addr, self)
                        };
                        const_expr_result
                            .map(|res| res.unwrap_validated().try_into().unwrap_validated())
                    })
                    .collect::<Result<Vec<Ref>, RuntimeError>>()?,
            };

            // SAFETY: The initial values were retrieved by (1) resolving
            // function indices or (2) running constant expressions in the
            // context of the current store. Therefore, their results are also
            // valid in the current store.
            let elem = unsafe { self.alloc_elem(elem.ty(), refs) };
            Ok::<_, RuntimeError>(elem)
        })?;

        // instantiation: step 11 - module allocation (except function allocation - which was made in step 5)
        // https://webassembly.github.io/spec/core/exec/modules.html#alloc-module

        // allocation: begin

        // allocation: step 1
        let module = validation_info;

        // allocation: skip step 2 & 8 as it was done in instantiation step 5

        // allocation: step 3, 9
        let table_addrs_local: Vec<TableAddr> = module
            .tables
            .iter_local_definitions()
            .map(|table_type| {
                // SAFETY: The initial table value is null, which is not an
                // address type and therefore not invalid in the current store.
                unsafe { self.alloc_table(*table_type, Ref::Null(table_type.et)) }
            })
            .collect();
        // allocation: step 4, 10
        let mem_addrs_local: Vec<MemAddr> = module
            .memories
            .iter_local_definitions()
            .map(|mem_type| self.alloc_mem(*mem_type))
            .collect();
        // allocation: step 5, 11
        let global_addrs_local: Vec<GlobalAddr> = module
            .globals
            .iter_local_definitions()
            .zip(local_globals_init_vals)
            .map(|(global, val)| {
                // SAFETY: The initial values were retrieved by running constant
                // expressions within the current store context. Therefore,
                // their results are also valid in the current store.
                unsafe { self.alloc_global(global.ty, val) }
            })
            .collect();
        // allocation: skip step 6, 12 as it was done in instantiation step 9, 10

        // allocation: step 7, 13
        let data_addrs = module
            .data
            .map::<DataAddr, Infallible>(|data_segment| Ok(self.alloc_data(&data_segment.init)))
            .expect("infallible error type to never be constructed");

        // allocation: skip step 14 as it was done in instantiation step 5

        // allocation: step 15
        let table_addrs = validation_info
            .tables
            .map(extern_vals.iter().tables().collect(), table_addrs_local)
            .expect(
                "that the numbers of imported and local tables always \
                match the respective numbers in the validation info. Step 3 and 4 \
                check if the number of imported tables is correct and the number \
                of local tables is produced by iterating through all table \
                definitions and performing one-to-one mapping on each one.",
            )
            .into_inner();

        // allocation: step 16
        let mem_addrs = validation_info
            .memories
            .map(extern_vals.iter().mems().collect(), mem_addrs_local)
            .expect(
                "that the number of imported and local memories always \
            match the respective numbers in the validation info. Step 3 and 4 \
            check if the number of imported memories is correct and the number \
            of local memories is produced by iterating through all memory \
            definitions and performing one-to-one mapping on each one.",
            )
            .into_inner();

        // allocation step 17
        let global_addrs = validation_info
            .globals
            .map(extern_vals.iter().globals().collect(), global_addrs_local)
            .expect(
                "that the number of imported and local globals always \
            match the respective numbers in the validation info. Step 3 and 4 \
            check if the number of imported globals is correct and the number \
            of local globals is produced by iterating through all global \
            definitions and performing one-to-one mapping on each one.",
            )
            .into_inner();

        // allocation: step 18,19
        let export_insts: BTreeMap<String, ExternVal> = module
            .exports
            .iter()
            .map(|export| {
                // SAFETY: The module with this module address was just inserted
                // into this `AddrVec`
                let module_inst = unsafe { self.modules.get(module_addr) };
                let value = match export.desc {
                    ExportDesc::Func(func_idx) => {
                        // SAFETY: Both the function index and the functions
                        // `IdxVec` come from the same module instance.
                        // Because all indices are valid in their specific
                        // module instance, this is sound.
                        let func_addr = unsafe { module_inst.func_addrs.get(func_idx) };
                        ExternVal::Func(*func_addr)
                    }
                    ExportDesc::Table(table_idx) => {
                        // SAFETY: Both the table index and the tables `IdxVec`
                        // come from the same module instance. Because all
                        // indices are valid in their specific module instance,
                        // this is sound.
                        let table_addr = unsafe { table_addrs.get(table_idx) };
                        ExternVal::Table(*table_addr)
                    }
                    ExportDesc::Mem(mem_idx) => {
                        // SAFETY: Both the memory index and the memories
                        // `IdxVec` come from the same module instance. Because
                        // all indices are valid in their specific module
                        // instance, this is sound.
                        let mem_addr = unsafe { mem_addrs.get(mem_idx) };

                        ExternVal::Mem(*mem_addr)
                    }
                    ExportDesc::Global(global_idx) => {
                        // SAFETY: Both the global index and the globals
                        // `ExtendedIdxVec` come from the same module instance.
                        // Because all indices are valid in their specific
                        // module instance, this is sound.
                        let global_addr = unsafe { global_addrs.get(global_idx) };

                        ExternVal::Global(*global_addr)
                    }
                };
                (export.name.to_owned(), value)
            })
            .collect();

        // allocation: step 20,21 initialize module (except functions to instantiation step 5, allocation step 14)

        // SAFETY: The module with this module address was
        // just inserted into this `AddrVec`
        let module_inst = unsafe { self.modules.get_mut(module_addr) };
        module_inst.table_addrs = table_addrs;
        module_inst.mem_addrs = mem_addrs;
        module_inst.global_addrs = global_addrs;
        module_inst.elem_addrs = elem_addrs;
        module_inst.data_addrs = data_addrs;
        module_inst.exports = export_insts;

        // allocation: end

        // instantiation step 11 end: module_inst properly allocated after this point.

        // instantiation: step 12-15
        // TODO have to stray away from the spec a bit since our codebase does not lend itself well to freely executing instructions by themselves
        for (
            element_idx,
            ElemType {
                init: elem_items,
                mode,
            },
        ) in validation_info.elements.iter_enumerated()
        {
            match mode {
                ElemMode::Active(ActiveElem {
                    table_idx: table_idx_i,
                    init_expr: einstr_i,
                }) => {
                    let n = elem_items.len() as u32;
                    // equivalent to init.len() in spec
                    // instantiation step 14:
                    // TODO (for now, we are doing hopefully what is equivalent to it)
                    // execute:
                    //   einstr_i
                    //   i32.const 0
                    //   i32.const n
                    //   table.init table_idx_i i
                    //   elem.drop i

                    // SAFETY: The module with this module address was just
                    // inserted into this `AddrVec`. Furthermore, the span comes
                    // from an element contained in the same validation info the
                    // Wasm bytecode is from. Therefore, the constant expression
                    // in that span must be validated already.
                    let const_expr_result = unsafe {
                        run_const_span(validation_info.wasm, einstr_i, module_addr, self)?
                    };
                    let d: i32 = const_expr_result
                        .unwrap_validated() // there is a return value
                        .try_into()
                        .unwrap_validated(); // return value has correct type

                    let s = 0;
                    // SAFETY: All requirements are met:
                    // 1. The module address was just retrieved by inserting a
                    //    new module instance into the current store. Therefore, it
                    //    is valid in the current store.
                    // 2. The table index is valid for the current module
                    //    instance because it came from the validation info of the
                    //    same module.
                    // 3./5. The table and element addresses are valid because
                    //       they come from a module instance that is part of the
                    //       current store itself.
                    // 4. The element index is valid for the current module
                    //    instance because it came from the validation info of the
                    //    same module.
                    unsafe {
                        table_init(
                            &self.modules,
                            &mut self.inner.tables,
                            &self.inner.elements,
                            module_addr,
                            element_idx,
                            *table_idx_i,
                            n,
                            s,
                            d,
                        )?
                    };
                    // SAFETY: All requirements are met:
                    // 1. The module address was just retrieved by inserting a
                    //    new module instance into the current store. Therefore, it
                    //    is valid in the current store.
                    // 2. The element index is valid for the current module
                    //    instance because it came from the validation info of the
                    //    same module.
                    // 3. The element address is valid because it comes from a
                    //    module instance that is part of the current store itself.
                    unsafe {
                        elem_drop(
                            &self.modules,
                            &mut self.inner.elements,
                            module_addr,
                            element_idx,
                        );
                    }
                }
                ElemMode::Declarative => {
                    // instantiation step 15:
                    // TODO (for now, we are doing hopefully what is equivalent to it)
                    // execute:
                    //   elem.drop i

                    // SAFETY: The passed element index comes from the
                    // validation info, that was just used to allocate a new
                    // module instance with address `module_addr` in
                    // `self.modules`. Therefore, it must be safe to use for
                    // accessing the referenced element.
                    // SAFETY: All requirements are met:
                    // 1. The module address was just retrieved by inserting a
                    //    new module instance into the current store. Therefore, it
                    //    is valid in the current store.
                    // 2. The element index is valid for the current module
                    //    instance because it came from the validation info of the
                    //    same module.
                    // 3. The element address is valid because it comes from a
                    //    module instance that is part of the current store itself.
                    unsafe {
                        elem_drop(
                            &self.modules,
                            &mut self.inner.elements,
                            module_addr,
                            element_idx,
                        );
                    }
                }
                ElemMode::Passive => (),
            }
        }

        // instantiation: step 16
        // TODO have to stray away from the spec a bit since our codebase does not lend itself well to freely executing instructions by themselves
        for (i, DataSegment { init, mode }) in validation_info.data.iter_enumerated() {
            match mode {
                DataMode::Active(DataModeActive {
                    memory_idx,
                    offset: dinstr_i,
                }) => {
                    let n = init.len() as u32;

                    // TODO (for now, we are doing hopefully what is equivalent to it)
                    // execute:
                    //   dinstr_i
                    //   i32.const 0
                    //   i32.const n
                    //   memory.init i
                    //   data.drop i
                    // SAFETY: The module with this module address was just
                    // inserted into this `AddrVec`. Furthermore, the span comes
                    // from a data segment contained in the same validation info
                    // the Wasm bytecode is from. Therefore, the constant
                    // expression in that span must be validated already.
                    let const_expr_result = unsafe {
                        run_const_span(validation_info.wasm, dinstr_i, module_addr, self)?
                    };
                    let d: u32 = const_expr_result
                        .unwrap_validated() // there is a return value
                        .try_into()
                        .unwrap_validated(); // return value has the correct type

                    let s = 0;
                    // SAFETY: All requirements are met:
                    // 1. The module address was just retrieved by inserting a
                    //    new module instance into the current store. Therefore, it
                    //    is valid in the current store.
                    // 2. The memory index is valid for the current module
                    //    instance because it came from the validation info of the
                    //    same module.
                    // 3./5. The memory and data addresses are valid because
                    //       they come from a module instance that is part of the
                    //       current store itself.
                    // 4. The data index is valid for the current module
                    //    instance because it came from the validation info of the
                    //    same module.
                    unsafe {
                        memory_init(
                            &self.modules,
                            &mut self.inner.memories,
                            &self.inner.data,
                            module_addr,
                            i,
                            *memory_idx,
                            n,
                            s,
                            d,
                        )
                    }?;

                    // SAFETY: All requirements are met:
                    // 1. The module address was just retrieved by inserting a
                    //    new module instance into the current store. Therefore, it
                    //    is valid in the current store.
                    // 2. The data index is valid for the current module
                    //    instance because it came from the validation info of the
                    //    same module.
                    // 3. The data address is valid because it comes from a
                    //    module instance that is part of the current store itself.
                    unsafe { data_drop(&self.modules, &mut self.inner.data, module_addr, i) };
                }
                DataMode::Passive => (),
            }
        }

        // instantiation: step 17
        let maybe_remaining_fuel = if let Some(func_idx) = validation_info.start {
            // TODO (for now, we are doing hopefully what is equivalent to it)
            // execute
            //   call func_ifx

            // SAFETY: The module with this module address was just inserted
            // into this `AddrVec`
            let module = unsafe { self.modules.get(module_addr) };
            // SAFETY: The function index comes from the passed `Module`
            // and the `IdxVec<FuncIdx, FuncAddr>` comes from the module
            // instance that originated from that same `Module`.
            // Therefore, this is sound.
            let func_addr = unsafe { module.func_addrs.get(func_idx) };

            // SAFETY: The function address just came from the current module
            // and is therefore valid in the current store. Furthermore, there
            // are no function arguments and thus also no other address types
            // can be invalid.
            let create_resumable_outcome =
                unsafe { self.create_resumable(*func_addr, Vec::new(), maybe_fuel) }?;

            let Resumable::Wasm(resumable) = create_resumable_outcome else {
                todo!("calling host functions from the start function");
            };

            // SAFETY: The resumable just came from the current store.
            // Therefore, it is always valid in the current store.
            match unsafe { self.resume_wasm(resumable) }? {
                RunState::Finished {
                    maybe_remaining_fuel,
                    ..
                } => maybe_remaining_fuel,
                RunState::Resumable { .. } => return Err(RuntimeError::OutOfFuel),
                RunState::HostCalled { .. } => {
                    return Err(RuntimeError::UnsupportedHostCallDuringInstantiation);
                }
            }
        } else {
            maybe_fuel
        };

        Ok(InstantiationOutcome {
            module_addr,
            maybe_remaining_fuel,
        })
    }

    /// Gets an export of a specific module instance by its name
    ///
    /// See: WebAssembly Specification 2.0 - 7.1.6 - instance_export
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the [`ModuleAddr`] came from the
    /// current [`Store`] object.
    pub unsafe fn instance_export(
        &self,
        module_addr: ModuleAddr,
        name: &str,
    ) -> Result<ExternVal, RuntimeError> {
        // Fetch the module instance because we store them in the [`Store`]
        // SAFETY: The caller ensures the module address to be valid in the
        // current store.
        let module_inst = unsafe { self.modules.get(module_addr) };

        // 1. Assert: due to validity of the module instance `moduleinst`, all its export names are different

        // 2. If there exists an `exportinst_i` in `moduleinst.exports` such that name `exportinst_i.name` equals `name`, then:
        //   a. Return the external value `exportinst_i.value`.
        // 3. Else return `error`.
        module_inst
            .exports
            .get(name)
            .copied()
            .ok_or(RuntimeError::UnknownExport)
    }

    /// Allocates a new function with some host code.
    ///
    /// This type of function is also called a host function.
    ///
    /// # Panics & Unexpected Behavior
    /// The specification states that:
    ///
    /// > This operation must make sure that the provided host function satisfies the pre-
    /// > and post-conditions required for a function instance with type `functype`.
    ///
    /// Therefore, all "invalid" host functions (e.g. those which return incorrect return values)
    /// can cause the interpreter to panic or behave unexpectedly.
    ///
    /// See: <https://webassembly.github.io/spec/core/exec/modules.html#host-functions>
    /// See: WebAssembly Specification 2.0 - 7.1.7 - func_alloc
    pub fn func_alloc(&mut self, func_type: FuncType, hostcode: Hostcode) -> FuncAddr {
        // 1. Pre-condition: `functype` is valid.

        // 2. Let `funcaddr` be the result of allocating a host function in `store` with
        //    function type `functype` and host function code `hostfunc`.
        // 3. Return the new store paired with `funcaddr`.
        //
        // Note: Returning the new store is a noop for us because we mutate the store instead.
        self.inner
            .functions
            .insert(FuncInst::HostFunc(HostFuncInst {
                function_type: func_type,
                hostcode,
            }))
    }

    /// Gets the type of a function by its addr.
    ///
    /// See: WebAssembly Specification 2.0 - 7.1.7 - func_type
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the [`FuncAddr`] came from the current
    /// [`Store`] object.
    pub unsafe fn func_type(&self, func_addr: FuncAddr) -> FuncType {
        // 1. Return `S.funcs[a].type`.
        // SAFETY: The caller ensures this function address to be valid for the
        // current store.
        let function = unsafe { self.inner.functions.get(func_addr) };
        function.ty().clone()

        // 2. Post-condition: the returned function type is valid.
    }

    /// See: WebAssembly Specification 2.0 - 7.1.7 - func_invoke
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`FuncAddr`] and any [`FuncAddr`] or
    /// [`ExternAddr`](crate::ExternAddr) values contained in the parameter values came from the
    /// current [`Store`] object.
    pub unsafe fn invoke(
        &mut self,
        func_addr: FuncAddr,
        params: Vec<Value>,
        maybe_fuel: Option<u64>,
    ) -> Result<RunState, RuntimeError> {
        // SAFETY: The caller ensures that the function address and any function
        // addresses or extern addresses contained in the parameter values are
        // valid in the current store.
        let resumable = unsafe { self.create_resumable(func_addr, params, maybe_fuel)? };
        // SAFETY: The resumable just came from the current store. Therefore, it
        // must be valid in the current store.
        unsafe { self.resume(resumable) }
    }

    /// Allocates a new table with some table type and an initialization value `ref` and returns its table address.
    ///
    /// See: WebAssembly Specification 2.0 - 7.1.8 - table_alloc
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that any [`FuncAddr`] or [`ExternAddr`](crate::ExternAddr)
    /// values contained in `r#ref` came from the current [`Store`] object.
    pub unsafe fn table_alloc(
        &mut self,
        table_type: TableType,
        r#ref: Ref,
    ) -> Result<TableAddr, RuntimeError> {
        // Check pre-condition: ref has correct type
        if table_type.et != r#ref.ty() {
            return Err(RuntimeError::TableTypeMismatch);
        }

        // 1. Pre-condition: `tabletype` is valid

        // 2. Let `tableaddr` be the result of allocating a table in `store` with table type `tabletype`
        //    and initialization value `ref`.
        // SAFETY: The caller ensures that the reference is valid in the current
        // store.
        let table_addr = unsafe { self.alloc_table(table_type, r#ref) };

        // 3. Return the new store paired with `tableaddr`.
        //
        // Note: Returning the new store is a noop for us because we mutate the store instead.
        Ok(table_addr)
    }

    /// Gets the type of some table by its addr.
    ///
    /// See: WebAssembly Specification 2.0 - 7.1.8 - table_type
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`TableAddr`] came from
    /// the current [`Store`] object.
    pub unsafe fn table_type(&self, table_addr: TableAddr) -> TableType {
        // 1. Return `S.tables[a].type`.
        // SAFETY: The caller ensures that the given table address is valid in
        // the current store.
        let table = unsafe { self.inner.tables.get(table_addr) };
        table.ty

        // 2. Post-condition: the returned table type is valid.
    }

    /// Reads a single reference from a table by its table address and an index into the table.
    ///
    /// See: WebAssembly Specification 2.0 - 7.1.8 - table_read
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`TableAddr`] must come from
    /// the current [`Store`] object.
    pub unsafe fn table_read(&self, table_addr: TableAddr, i: u32) -> Result<Ref, RuntimeError> {
        // Convert `i` to usize for indexing
        let i = i.into_usize();

        // 1. Let `ti` be the table instance `store.tables[tableaddr]`
        // SAFETY: The caller ensures that the given table address is valid in
        // the current store.
        let ti = unsafe { self.inner.tables.get(table_addr) };

        // 2. If `i` is larger than or equal to the length of `ti.elem`, then return `error`.
        // 3. Else, return the reference value `ti.elem[i]`.
        ti.elem
            .get(i)
            .copied()
            .ok_or(RuntimeError::TableAccessOutOfBounds)
    }

    /// Writes a single reference into a table by its table address and an index into the table.
    ///
    /// See: WebAssembly Specification 2.0 - 7.1.8 - table_write
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`TableAddr`] and any [`FuncAddr`] or
    /// [`ExternAddr`](crate::ExternAddr) values contained in the [`Ref`] must come from the current
    /// [`Store`] object.
    pub unsafe fn table_write(
        &mut self,
        table_addr: TableAddr,
        i: u32,
        r#ref: Ref,
    ) -> Result<(), RuntimeError> {
        // Convert `i` to usize for indexing
        let i = i.into_usize();

        // 1. Let `ti` be the table instance `store.tables[tableaddr]`.
        // SAFETY: The caller ensures that the given table address is valid in
        // the current store.
        let ti = unsafe { self.inner.tables.get_mut(table_addr) };

        // Check pre-condition: ref has correct type
        if ti.ty.et != r#ref.ty() {
            return Err(RuntimeError::TableTypeMismatch);
        }

        // 2. If `i` is larger than or equal to the length of `ti.elem`, then return `error`.
        // 3. Replace `ti.elem[i]` with the reference value `ref`
        *ti.elem
            .get_mut(i)
            .ok_or(RuntimeError::TableAccessOutOfBounds)? = r#ref;

        // 4. Return the updated store.
        //
        // Note: Returning the new store is a noop for us because we mutate the store instead.
        Ok(())
    }

    /// Gets the current size of a table by its table address.
    ///
    /// See: WebAssembly Specification 2.0 - 7.1.8 - table_size
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`TableAddr`] must come from
    /// the current [`Store`] object.
    pub unsafe fn table_size(&self, table_addr: TableAddr) -> u32 {
        // 1. Return the length of `store.tables[tableaddr].elem`.
        // SAFETY: The caller ensures that the table address is valid in the
        // current store.
        let table = unsafe { self.inner.tables.get(table_addr) };
        let len = table.elem.len();

        // In addition we have to convert the length back to a `u32`
        u32::try_from(len).expect(
            "the maximum table length to be u32::MAX because thats what the specification allows for indexing",
        )
    }

    /// Grows a table referenced by its table address by `n` elements.
    ///
    /// See: WebAssembly Specification 2.0 - 7.1.8 - table_grow
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`TableAddr`] and any [`FuncAddr`] or
    /// [`ExternAddr`](crate::ExternAddr) values contained in the [`Ref`] must come from the current
    /// [`Store`] object.
    pub unsafe fn table_grow(
        &mut self,
        table_addr: TableAddr,
        n: u32,
        r#ref: Ref,
    ) -> Result<(), RuntimeError> {
        // 1. Try growing the table instance `store.tables[tableaddr] by `n` elements with initialization value `ref`:
        //   a. If it succeeds, return the updated store.
        //   b. Else, return `error`.
        //
        // Note: Returning the new store is a noop for us because we mutate the store instead.
        // SAFETY: The caller ensures that the given table address is valid in
        // the current store.
        let table = unsafe { self.inner.tables.get_mut(table_addr) };
        table.grow(n, r#ref)
    }

    /// Allocates a new linear memory and returns its memory address.
    ///
    /// See: WebAssembly Specification 2.0 - 7.1.9 - mem_alloc
    pub fn mem_alloc(&mut self, mem_type: MemType) -> MemAddr {
        // 1. Pre-condition: `memtype` is valid.

        // 2. Let `memaddr` be the result of allocating a memory in `store` with memory type `memtype`.
        // 3. Return the new store paired with `memaddr`.
        //
        // Note: Returning the new store is a noop for us because we mutate the store instead.
        self.alloc_mem(mem_type)
    }

    /// Gets the memory type of some memory by its memory address
    ///
    /// See: WebAssemblySpecification 2.0 - 7.1.9 - mem_type
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`MemAddr`] came from the
    /// current [`Store`] object.
    pub unsafe fn mem_type(&self, mem_addr: MemAddr) -> MemType {
        // 1. Return `S.mems[a].type`.
        // SAFETY: The caller ensures that the given memory address is valid in
        // the current store.
        let memory = unsafe { self.inner.memories.get(mem_addr) };
        memory.ty

        // 2. Post-condition: the returned memory type is valid.
    }

    /// Reads a byte from some memory by its memory address and an index into the memory
    ///
    /// See: WebAssemblySpecification 2.0 - 7.1.9 - mem_read
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`MemAddr`] came from the
    /// current [`Store`] object.
    pub unsafe fn mem_read(&self, mem_addr: MemAddr, i: u32) -> Result<u8, RuntimeError> {
        // Convert the index type
        let i = i.into_usize();

        // 1. Let `mi` be the memory instance `store.mems[memaddr]`.
        // SAFETY: The caller ensures that the given memory address is valid in
        // the current store.
        let mi = unsafe { self.inner.memories.get(mem_addr) };

        // 2. If `i` is larger than or equal to the length of `mi.data`, then return `error`.
        // 3. Else, return the byte `mi.data[i]`.
        mi.mem.load(i)
    }

    /// Writes a byte into some memory by its memory address and an index into the memory
    ///
    /// See: WebAssemblySpecification 2.0 - 7.1.9 - mem_write
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`MemAddr`] came from the
    /// current [`Store`] object.
    pub unsafe fn mem_write(
        &self,
        mem_addr: MemAddr,
        i: u32,
        byte: u8,
    ) -> Result<(), RuntimeError> {
        // Convert the index type
        let i = i.into_usize();

        // 1. Let `mi` be the memory instance `store.mems[memaddr]`.
        // SAFETY: The caller ensures that the given memory address is valid in
        // the current store.
        let mi = unsafe { self.inner.memories.get(mem_addr) };

        mi.mem.store(i, byte)
    }

    /// Gets the size of some memory by its memory address in pages.
    ///
    /// See: WebAssemblySpecification 2.0 - 7.1.9 - mem_size
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`MemAddr`] came from the
    /// current [`Store`] object.
    pub unsafe fn mem_size(&self, mem_addr: MemAddr) -> u32 {
        // 1. Return the length of `store.mems[memaddr].data` divided by the page size.
        // SAFETY: The caller ensures that the given memory address is valid in
        // the current store.
        let memory = unsafe { self.inner.memories.get(mem_addr) };
        let length = memory.size();

        // In addition we have to convert the length back to a `u32`
        length.try_into().expect(
            "the maximum memory length to be smaller than u32::MAX because thats what the specification allows for indexing into the memory. Also the memory size is measured in pages, not bytes.")
    }

    /// Grows some memory by its memory address by `n` pages.
    ///
    /// See: WebAssemblySpecification 2.0 - 7.1.9 - mem_grow
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`MemAddr`] came from the
    /// current [`Store`] object.
    pub unsafe fn mem_grow(&mut self, mem_addr: MemAddr, n: u32) -> Result<(), RuntimeError> {
        // 1. Try growing the memory instance `store.mems[memaddr]` by `n` pages:
        //   a. If it succeeds, then return the updated store.
        //   b. Else, return `error`.
        //
        // Note: Returning the new store is a noop for us because we mutate the store instead.
        // SAFETY: The caller ensures that the given memory address is valid in
        // the current store.
        let memory = unsafe { self.inner.memories.get_mut(mem_addr) };
        memory.grow(n)
    }

    /// Allocates a new global and returns its global address.
    ///
    /// See: WebAssemblySpecification 2.0 - 7.1.10 - global_alloc
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that any [`FuncAddr`] or [`ExternAddr`](crate::ExternAddr)
    /// values contained in the [`Value`] came from the current [`Store`] object.
    pub unsafe fn global_alloc(
        &mut self,
        global_type: GlobalType,
        val: Value,
    ) -> Result<GlobalAddr, RuntimeError> {
        // Check pre-condition: val has correct type
        if global_type.ty != val.to_ty() {
            return Err(RuntimeError::GlobalTypeMismatch);
        }

        // 1. Pre-condition: `globaltype` is valid.

        // 2. Let `globaladdr` be the result of allocating a global with global type `globaltype` and initialization value `val`.
        // SAFETY: The caller ensures that any address types contained in the
        // initial value are valid in the current store.
        let global_addr = unsafe { self.alloc_global(global_type, val) };

        // 3. Return the new store paired with `globaladdr`.
        //
        // Note: Returning the new store is a noop for us because we mutate the store instead.
        Ok(global_addr)
    }

    /// Returns the global type of some global instance by its addr.
    ///
    /// See: WebAssembly Specification 2.0 - 7.1.10 - global_type
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`GlobalAddr`] came from the
    /// current [`Store`] object.
    pub unsafe fn global_type(&self, global_addr: GlobalAddr) -> GlobalType {
        // 1. Return `S.globals[a].type`.
        // SAFETY: The caller ensures that the given global address is valid in
        // the current store.
        let global = unsafe { self.inner.globals.get(global_addr) };
        global.ty
        // 2. Post-condition: the returned global type is valid
    }

    /// Returns the current value of some global instance by its addr.
    ///
    /// See: WebAssembly Specification 2.0 - 7.1.10 - global_read
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`GlobalAddr`] came from the
    /// current [`Store`] object.
    pub unsafe fn global_read(&self, global_addr: GlobalAddr) -> Value {
        // 1. Let `gi` be the global instance `store.globals[globaladdr].
        // SAFETY: The caller ensures that the given global address is valid in
        // the current store.
        let gi = unsafe { self.inner.globals.get(global_addr) };

        // 2. Return the value `gi.value`.
        gi.value
    }

    /// Sets a new value of some global instance by its addr.
    ///
    /// # Errors
    /// - [` RuntimeError::WriteOnImmutableGlobal`]
    /// - [` RuntimeError::GlobalTypeMismatch`]
    ///
    /// See: WebAssembly Specification 2.0 - 7.1.10 - global_write
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`GlobalAddr`] and any [`FuncAddr`] or
    /// [`ExternAddr`](crate::ExternAddr) values contained in the [`Value`] came from the current
    /// [`Store`] object.
    pub unsafe fn global_write(
        &mut self,
        global_addr: GlobalAddr,
        val: Value,
    ) -> Result<(), RuntimeError> {
        // 1. Let `gi` be the global instance `store.globals[globaladdr]`.
        // SAFETY: The caller ensures that the given global address is valid in the current module.
        let gi = unsafe { self.inner.globals.get_mut(global_addr) };

        // 2. Let `mut t` be the structure of the global type `gi.type`.
        let r#mut = gi.ty.is_mut;
        let t = gi.ty.ty;

        // 3. If `mut` is not `var`, then return error.
        if !r#mut {
            return Err(RuntimeError::WriteOnImmutableGlobal);
        }

        // Check invariant:
        //   It is an invariant of the semantics that the value has a type equal to the value type of `globaltype`.
        // See: WebAssembly Specification 2.0 - 4.2.9
        if t != val.to_ty() {
            return Err(RuntimeError::GlobalTypeMismatch);
        }

        // 4. Replace `gi.value` with the value `val`.
        gi.value = val;

        // 5. Return the updated store.
        // This is a noop for us, as our store `self` is mutable.

        Ok(())
    }

    /// roughly matches <https://webassembly.github.io/spec/core/exec/modules.html#functions> with the addition of sidetable pointer to the input signature
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that
    /// - the given [`ModuleAddr`] came from the current [`Store`] object.
    /// - the given [`TypeIdx`] is valid in the module for the given [`ModuleAddr`].
    // TODO refactor the type of func
    unsafe fn alloc_func(
        &mut self,
        func: (TypeIdx, (Span, usize)),
        module_addr: ModuleAddr,
    ) -> FuncAddr {
        let (ty, (span, stp)) = func;

        // TODO rewrite this huge chunk of parsing after generic way to re-parse(?) structs lands
        // SAFETY: The caller ensures that the given module address is valid in
        // the current store.
        let module = unsafe { self.modules.get(module_addr) };
        let mut wasm_reader = WasmDecoder::new(module.wasm_bytecode);
        wasm_reader.move_start_to(span).unwrap_validated();

        let (locals, bytes_read) = wasm_reader
            .measure_num_read_bytes(decode_locals)
            .unwrap_validated();

        let code_expr = wasm_reader
            .make_span(span.len() - bytes_read)
            .unwrap_validated();

        // core of the method below

        // validation guarantees func_ty_idx exists within module_inst.types
        // TODO fix clone
        // SAFETY: The caller guarantees that the given type index is valid for
        // this module.
        let function_type = unsafe { module.types.get(ty).clone() };
        let func_inst = FuncInst::WasmFunc(WasmFuncInst {
            function_type,
            _ty: ty,
            locals,
            code_expr,
            stp,
            module_addr,
        });
        self.inner.functions.insert(func_inst)
    }

    /// <https://webassembly.github.io/spec/core/exec/modules.html#tables>
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that any [`FuncAddr`] or [`ExternAddr`](crate::ExternAddr)
    /// values contained in the [`Ref`] came from the current [`Store`] object.
    unsafe fn alloc_table(&mut self, table_type: TableType, reff: Ref) -> TableAddr {
        let table_inst = TableInst {
            ty: table_type,
            elem: vec![reff; table_type.lim.min.into_usize()],
        };

        self.inner.tables.insert(table_inst)
    }

    /// <https://webassembly.github.io/spec/core/exec/modules.html#memories>
    fn alloc_mem(&mut self, mem_type: MemType) -> MemAddr {
        let mem_inst = MemInst {
            ty: mem_type,
            mem: LinearMemory::new_with_initial_pages(
                mem_type.limits.min.try_into().unwrap_validated(),
            ),
        };

        self.inner.memories.insert(mem_inst)
    }

    /// <https://webassembly.github.io/spec/core/exec/modules.html#globals>
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that any [`FuncAddr`] or [`ExternAddr`](crate::ExternAddr)
    /// values contained in the [`Value`] came from the current [`Store`] object.
    unsafe fn alloc_global(&mut self, global_type: GlobalType, val: Value) -> GlobalAddr {
        let global_inst = GlobalInst {
            ty: global_type,
            value: val,
        };

        self.inner.globals.insert(global_inst)
    }

    /// <https://webassembly.github.io/spec/core/exec/modules.html#element-segments>
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that any [`FuncAddr`] or [`ExternAddr`](crate::ExternAddr)
    /// values contained in
    /// the [`Ref`]s came from the current [`Store`] object.
    unsafe fn alloc_elem(&mut self, ref_type: RefType, refs: Vec<Ref>) -> ElemAddr {
        let elem_inst = ElemInst {
            _ty: ref_type,
            references: refs,
        };

        self.inner.elements.insert(elem_inst)
    }

    /// <https://webassembly.github.io/spec/core/exec/modules.html#data-segments>
    fn alloc_data(&mut self, bytes: &[u8]) -> DataAddr {
        let data_inst = DataInst {
            data: Vec::from(bytes),
        };

        self.inner.data.insert(data_inst)
    }

    /// Creates a new resumable, which when resumed for the first time invokes the function `function_ref` is associated
    /// to, with the arguments `params`. The newly created resumable initially stores `fuel` units of fuel. Returns a
    /// `[ResumableRef]` associated to the newly created resumable on success.
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the [`FuncAddr`] and any [`FuncAddr`] or
    /// [`ExternAddr`](crate::ExternAddr) values contained in the parameter values came from the
    /// current [`Store`] object.
    pub unsafe fn create_resumable(
        &self,
        func_addr: FuncAddr,
        params: Vec<Value>,
        maybe_fuel: Option<u64>,
    ) -> Result<Resumable, RuntimeError> {
        // SAFETY: The caller ensures that this function address is valid in the
        // current store.
        let func_inst = unsafe { self.inner.functions.get(func_addr) };

        let func_ty = func_inst.ty();

        // Verify that the given parameter types match the function parameter types
        if func_ty.params.valtypes.len() != params.len() {
            return Err(RuntimeError::FunctionInvocationSignatureMismatch);
        }

        let type_mismatch = func_ty
            .params
            .valtypes
            .iter()
            .zip(&params)
            .any(|(func_val_ty, param_val)| func_val_ty != &param_val.to_ty());

        if type_mismatch {
            return Err(RuntimeError::FunctionInvocationSignatureMismatch);
        };

        let resumable = match func_inst {
            FuncInst::WasmFunc(wasm_func_inst) => {
                // Prepare a new stack with the locals for the entry function
                let stack = Stack::new::<T>(
                    params,
                    &wasm_func_inst.function_type,
                    &wasm_func_inst.locals,
                )?;

                Resumable::Wasm(WasmResumable {
                    current_func_addr: func_addr,
                    stack,
                    pc: wasm_func_inst.code_expr.from,
                    stp: wasm_func_inst.stp,
                    maybe_fuel,
                })
            }
            FuncInst::HostFunc(host_func_inst) => Resumable::Host {
                host_call: HostCall {
                    params,
                    hostcode: host_func_inst.hostcode,
                },
                host_resumable: HostResumable {
                    host_func_addr: func_addr,
                    inner_resumable: None,
                    maybe_fuel: Some(maybe_fuel),
                },
            },
        };

        Ok(resumable)
    }

    /// Resumes execution of a [`Resumable`], regardless of its inner representation.
    ///
    /// Note: The [`Resumable`] may also be deconstructed by the user and its
    /// contents used with [`Store::resume_wasm`] or
    /// [`Store::finish_host_call`].
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the [`Resumable`] came from the current
    /// [`Store`] object.
    pub unsafe fn resume(&mut self, resumable: Resumable) -> Result<RunState, RuntimeError> {
        match resumable {
            // SAFETY: The caller ensures that this `WasmResumable` came from
            // the current store.
            Resumable::Wasm(wasm_resumable) => unsafe { self.resume_wasm(wasm_resumable) },
            Resumable::Host {
                host_call,
                host_resumable,
            } => Ok(RunState::HostCalled {
                host_call,
                resumable: host_resumable,
            }),
        }
    }

    /// Resumes the given [`WasmResumable`]. Returns a [`RunState`] that may contain
    /// a new [`Resumable`] depending on whether execution ran out of fuel or
    /// finished normally.
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the [`Resumable`] came from the current
    /// [`Store`] object.
    pub unsafe fn resume_wasm(
        &mut self,
        mut resumable: WasmResumable,
    ) -> Result<RunState, RuntimeError> {
        // SAFETY: The caller guarantees that the resumable comes from the current store.
        let result = unsafe { instructions::run(&mut resumable, self) }?;

        let run_state = match result {
            InterpreterLoopOutcome::ExecutionReturned => RunState::Finished {
                values: resumable.stack.into_values(),
                maybe_remaining_fuel: resumable.maybe_fuel,
            },
            InterpreterLoopOutcome::OutOfFuel { required_fuel } => RunState::Resumable {
                resumable,
                required_fuel: Some(required_fuel),
            },
            InterpreterLoopOutcome::HostCalled {
                func_addr,
                params,
                hostcode,
            } => RunState::HostCalled {
                host_call: HostCall { params, hostcode },
                resumable: HostResumable {
                    host_func_addr: func_addr,
                    inner_resumable: Some(resumable),
                    maybe_fuel: None,
                },
            },
        };

        Ok(run_state)
    }

    /// To be executed after executing a [`HostCall`].
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the [`HostResumable`] and all
    /// addresses in the return values came from the current [`Store`] object.
    pub unsafe fn finish_host_call(
        &mut self,
        host_resumable: HostResumable,
        host_call_return_values: Vec<Value>,
    ) -> Result<RunState, RuntimeError> {
        // Verify that the return parameters match the host function parameters
        // since we have no validation guarantees for host functions

        // SAFETY: The caller ensures that the `HostResumable`, and thus also
        // the function address in it, is valid in the current store.
        let function = unsafe { self.inner.functions.get(host_resumable.host_func_addr) };

        let FuncInst::HostFunc(host_func_inst) = function else {
            unreachable!("expected function to be a host function instance")
        };

        let return_types = host_call_return_values
            .iter()
            .map(|v| v.to_ty())
            .collect::<Vec<_>>();

        if host_func_inst.function_type.returns.valtypes != return_types {
            return Err(RuntimeError::HostFunctionSignatureMismatch);
        }

        if let Some(mut wasm_resumable) = host_resumable.inner_resumable {
            for return_value in host_call_return_values {
                wasm_resumable.stack.push_value(return_value)?;
            }

            Ok(RunState::Resumable {
                resumable: wasm_resumable,
                required_fuel: None,
            })
        } else {
            Ok(RunState::Finished {
                values: host_call_return_values,
                maybe_remaining_fuel: host_resumable
                    .maybe_fuel
                    .expect("this to be set if the inner WasmResumable is None"),
            })
        }
    }

    /// Invokes a function without support for fuel or host functions.
    ///
    /// This function wraps [`Store::invoke`].
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`FuncAddr`] and any [`FuncAddr`] or
    /// [`ExternAddr`](crate::ExternAddr) values contained in the parameter values came from the
    /// current [`Store`] object.
    pub unsafe fn invoke_simple(
        &mut self,
        function: FuncAddr,
        params: Vec<Value>,
    ) -> Result<Vec<Value>, RuntimeError> {
        // SAFETY: The caller ensures that the given function address and all
        // address types contained in the parameters are valid in the current
        // store.
        let run_state = unsafe { self.invoke(function, params, None) }?;

        match run_state {
            RunState::Finished {
                values,
                maybe_remaining_fuel: _,
            } => Ok(values),
            RunState::Resumable { .. } => unreachable!("fuel is disabled"),
            RunState::HostCalled { .. } => Err(RuntimeError::UnexpectedHostCall),
        }
    }

    /// Allows a given closure to temporarily access the entire memory as a
    /// `&mut [u8]`.
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`MemAddr`] came from the
    /// current [`Store`] object.
    pub unsafe fn mem_access_mut_slice<R>(
        &self,
        memory: MemAddr,
        accessor: impl FnOnce(&mut [u8]) -> R,
    ) -> R {
        // SAFETY: The caller ensures that the given memory address is valid in
        // the current store.
        let memory = unsafe { self.inner.memories.get(memory) };
        memory.mem.access_mut_slice(accessor)
    }

    /// Returns all exports of a module instance by its module address.
    ///
    /// To get a single import by its known name, use
    /// [`Store::instance_export`].
    ///
    /// # Safety
    ///
    /// The caller has to guarantee that the given [`ModuleAddr`] came from the
    /// current [`Store`] object.
    pub unsafe fn instance_exports(&self, module_addr: ModuleAddr) -> Vec<(String, ExternVal)> {
        // SAFETY: The caller ensures that the given module address is valid in
        // the current store.
        let module = unsafe { self.modules.get(module_addr) };

        module
            .exports
            .iter()
            .map(|(name, externval)| (name.clone(), *externval))
            .collect()
    }
}

/// Represents a successful, possibly fueled instantiation of a module.
pub struct InstantiationOutcome {
    /// contains the store address of the module that has successfully instantiated.
    pub module_addr: ModuleAddr,
    /// contains `Some(remaining_fuel)` if instantiation was fuel-metered and `None` otherwise.
    pub maybe_remaining_fuel: Option<u64>,
}

pub type Hostcode = usize;