docs: update architecture, docs

Signed-off-by: Henry <mail@henrygressmann.de>

Author: explodingcamera

ARCHITECTURE.md

@@ -1,62 +1,74 @@
 # TinyWasm Architecture
 
-TinyWasm follows the general runtime model described in the [WebAssembly specification](https://webassembly.github.io/spec/core/exec/runtime.html), but lowers validated WebAssembly into a compact internal instruction format before execution.
+TinyWasm follows the general runtime model described in the [WebAssembly specification](https://webassembly.github.io/spec/core/exec/runtime.html). It is a stack-based interpreter with a compact internal bytecode, width-specific value stacks, and configurable linear-memory backends.
 
-## Runtime Layout
+## Execution Pipeline
 
-- Values are stored in untyped stacks:
-  - `stack_32` for `i32`, `f32`, `funcref`, and `externref`
-  - `stack_64` for `i64` and `f64`
-  - `stack_128` for `v128`
-- Locals are stored directly in the value stacks. Each `CallFrame` stores a `locals_base`, and local instructions index from that base.
-- Structured control flow (`block`, `loop`, `if`, `br*`) is lowered during parsing to jump-oriented internal instructions such as `Jump`, `JumpIfZero`, `BranchTable*`, `DropKeep*`, and `Return`.
-- Execution is a single iterative interpreter loop over the lowered instruction stream.
+TinyWasm does not execute WebAssembly instructions directly. Parsing lowers them into an internal bytecode designed to make execution simpler and cheaper:
 
-## Internal Bytecode
+- structured control flow (`block`, `loop`, `if`, and `br*`) becomes jump-oriented instructions such as `Jump`, `JumpIfZero`, `BranchTable*`, `DropKeep*`, and `Return`
+- operand widths are encoded in instruction variants, and branch stack reshaping is explicit
+- instructions retain compact module-local indexes, which each instance maps to Store-wide runtime addresses
+- when enabled, the optimizer applies local rewrites, including superinstruction fusion, specialized calls and returns, and redundant-instruction removal
+- modules can be serialized as `.twasm` archives containing this lowered representation
+- execution uses a single iterative dispatch loop over the resulting instruction stream
 
-TinyWasm does not interpret WebAssembly instructions directly. During parsing and validation, WebAssembly is translated into TinyWasm's internal bytecode format.
+## Value Stacks
 
-This internal representation is designed to make execution simpler and cheaper:
+WebAssembly combines an operand stack with function-scoped locals. TinyWasm stores both in the same width-specific physical stacks:
 
-- structured control flow is resolved ahead of time
-- stack effects are made explicit
-- common instruction sequences can be fused into superinstructions
-- modules can optionally be serialized as `.twasm` for reuse
+- `stack_32` for `i32`, `f32`, and reference values, including GC and exception references
+- `stack_64` for `i64` and `f64`
+- `stack_128` for `v128`
 
-## Optimizer
+The interpreter does not maintain a runtime type stack or tag individual stack slots. Lowered instructions encode the physical lane they operate on, while WebAssembly validation guarantees type correctness. Splitting values by width lets each value use its natural storage size, reducing stack memory and the data moved by common operations.
 
-During parsing, a peephole optimizer (`optimize.rs`) fuses common instruction sequences into superinstructions. These reduce interpreter dispatch overhead by combining multiple logical operations into one internal instruction.
+Locals are stored directly in these stacks. Each `CallFrame` records a base for every lane, and lowered local instructions index from those bases. The value stacks and call stack can use either a fixed capacity or dynamic initial and maximum sizes. Dynamic stacks keep the initial allocation small, grow when needed, and retain a hard limit.
 
-Examples include:
+## Interpreter Optimization
 
-- **Fused binops**: `BinOpLocalLocal*`, `BinOpLocalConst*`, `BinOpStackGlobal*`  
-  Combine local/global access, a binary operation, and sometimes a store/tee.
-- **Fused jumps**: `JumpCmpLocalConst*`, `JumpCmpLocalLocal*`, `JumpCmpStackConst*`  
-  Combine comparison and conditional branch logic.
+Instruction dispatch is one of the interpreter's main costs. TinyWasm reduces it through superinstructions and by shaping the large Rust dispatch match based on benchmarks and assembly inspection. Most simple arithmetic remains directly in the interpreter loop. Small, frequently used stack, value, and global operations use `#[inline]` or `#[inline(always)]` where measurements show a benefit, while unlikely error paths use `core::hint::cold_path()`.
+
+Superinstructions also reduce value-stack traffic. They can read locals, globals, and constants directly, perform an operation, and write `set` or `tee` destinations without materializing intermediate operand-stack values. Examples include:
+
+- fused binary operations such as `BinOpLocalLocal*`, `BinOpLocalConst*`, and `BinOpStackGlobal*`
+- fused conditional branches such as `JumpCmpLocalConst*`, `JumpCmpLocalLocal*`, and `JumpCmpStackConst*`
+
+The default runtime remains safe Rust throughout rather than relying on unchecked operations.
+
+## SIMD
+
+SIMD instructions have a portable safe-Rust implementation built from fixed-size arrays and lane operations, relying on the compiler to auto-vectorize where possible. Generated code is inspected with `cargo asm`, and benchmarks determine where architecture-specific alternatives are worthwhile. WebAssembly targets use native SIMD intrinsics where available, while the optional `simd-x86` feature provides selected x86 implementations for operations where the generic code produces worse results.
 
 ## Memory Backends
 
 Linear memory is implemented through the `LinearMemory` trait. The backend is selected with `engine::Config::with_memory_backend()`.
 
+`LinearMemory` exposes separate fixed-width read and write methods for 8-, 16-, 32-, 64-, and 128-bit accesses. A const-generic method would not be callable through a `dyn LinearMemory` trait object, so each width is an explicit vtable entry that backends can optimize independently.
+
+This flexibility has a measurable cost: guest loads and stores cross the `dyn LinearMemory` boundary, adding an indirect call and generally preventing the backend operation from being inlined into the interpreter. The fixed-width methods keep the work behind that boundary as small and specialized as possible.
+
 Available backends:
 
-- `VecMemory` - contiguous `Vec<u8>` backing; the default backend.
-- `PagedMemory` - chunk-based allocation, useful when growing memory without reallocating one large buffer.
-- `LazyLinearMemory` - wraps another backend and allocates memory on first access.
+- `VecMemory` - contiguous `Vec<u8>` backing and the default backend.
+- `PagedMemory` - sparse chunk-based allocation, with untouched chunks left unallocated and growth avoiding relocation of one contiguous buffer.
+- `LazyLinearMemory` - serves zero-filled reads without allocation and creates the configured backend on the first mutation or growth.
 - Custom backends through `MemoryBackend::custom()`.
 
+`VecMemory` growth may reallocate, though operating-system allocators can often grow page-backed allocations without copying the full buffer. Applications on conventional operating systems should generally keep it unless sparse allocation or non-relocating growth is specifically needed. Bounded dynamic stacks and sparse paged memory trade some runtime overhead for a smaller initial footprint on embedded and other resource-constrained systems.
+
 ## Future Experiments
 
-TinyWasm's interpreter is intentionally simple today: validated WebAssembly is lowered to internal instructions, optimized with peephole fusion, and executed by an iterative dispatch loop.
+Future work may explore additional dispatch and code-generation strategies, including Rust's experimental `loop_match` state-machine work, a tail-call-based interpreter once Rust's explicit tail-call support matures, more aggressive superinstruction fusion, top-of-stack register allocation, or optional JIT compilation.
 
-Future work may explore additional dispatch and code-generation strategies, including Rust's experimental `loop_match` state-machine work, explicit tail calls, more aggressive superinstruction fusion, top-of-stack register allocation, or even optional JIT compilation.
+For conventional operating systems, a future `mmap`-based memory backend could reserve virtual address space and use guard pages to move more bounds enforcement to the operating system, reducing explicit checks in linear-memory hot paths. This is the same broad approach described in [Wasmtime's linear-memory architecture](https://docs.wasmtime.dev/contributing-architecture.html#linear-memory), where virtual-memory reservations and guard regions eliminate or deduplicate explicit bounds checks.
 
-## Code Map
+## Important Modules
 
-- [visit.rs](./crates/parser/src/visit.rs) - WebAssembly binary visitor
+- [visit.rs](./crates/parser/src/visit.rs) - function-body operator lowering
 - [optimize.rs](./crates/parser/src/optimize.rs) - peephole optimizer and superinstruction fusion
-- [parallel.rs](./crates/parser/src/parallel.rs) - multithreaded function parsing
+- [parallel.rs](./crates/parser/src/parallel.rs) - parallel function parsing
 - [instructions.rs](./crates/types/src/instructions.rs) - internal instruction set
-- [value_stack.rs](./crates/tinywasm/src/interpreter/stack/value_stack.rs) - typed value stacks
+- [value_stack.rs](./crates/tinywasm/src/interpreter/stack/value_stack.rs) - width-specific stacks
 - [call_stack.rs](./crates/tinywasm/src/interpreter/stack/call_stack.rs) - call frame stack
 - [memory/mod.rs](./crates/tinywasm/src/store/memory/mod.rs) - memory backend trait and implementations

README.md

@@ -7,7 +7,7 @@
 
 ## Why `tinywasm`?
 
-- **Tiny**: Small by design, without significantly compromising performance or functionality.
+- **Tiny**: Small by design, while still passing the full WebAssembly 3.0 core testsuite.
 - **Portable**: Runs anywhere Rust can target, supports `no_std`, has minimal dependencies, and can itself compile to WebAssembly.
 - **Safe**: Written in safe Rust, with optional `unsafe` limited to the `simd-x86` feature. Its sandbox is designed to prevent untrusted Wasm from accessing host memory or escaping the runtime.
 
@@ -42,6 +42,10 @@ assert_eq!(result, 3);
 
 See the [examples](./examples) directory and [documentation](https://docs.rs/tinywasm) for more information.
 
+## Precompiled Modules
+
+TinyWasm modules can be compiled to the internal `twasm` bytecode format, which stores the optimized instruction representation for faster loading and reuse.
+
 ## Cargo Features
 
 - **`std`:** Enables `std` and parsing from files and streams. Enabled by default.
@@ -61,12 +65,6 @@ Use `Engine` and `engine::Config` when you need non-default runtime settings suc
 
 [^libm]: [rust-lang/rust#137578](https://github.com/rust-lang/rust/issues/137578) — tracking issue for floating-point math support in `no_std`.
 
-## Current Status
-
-`tinywasm` passes the WebAssembly MVP and WebAssembly 2.0 core testsuites and supports the [Lime1](https://github.com/WebAssembly/tool-conventions/blob/main/Lime.md#lime1) interoperability target. WebAssembly 3.0 support is still in progress, and some newer proposal suites are tracked in-repo as experimental coverage rather than release guarantees; see [Supported Proposals](#supported-proposals) for details.
-
-TinyWasm also has its own internal bytecode format, `twasm`. WebAssembly modules can be compiled to `twasm`, which stores TinyWasm's optimized instruction representation for faster loading and reuse.
-
 ## Safety
 
 TinyWasm only uses safe Rust by default. The optional `simd-x86` feature enables x86-specific SIMD intrinsics and uses `unsafe` internally. WebAssembly input is validated by default through the `validate` feature. Disabling validation should not let Wasm access host memory or escape the sandbox, but malformed input may panic or otherwise crash the process, so only disable it for trusted input.

crates/tinywasm/src/lib.rs

@@ -7,12 +7,12 @@
 #![cfg_attr(not(feature = "simd-x86"), forbid(unsafe_code))]
 #![cfg_attr(feature = "simd-x86", deny(unsafe_code))]
 
-//! `tinywasm` provides a small, portable WebAssembly interpreter with support for
-//! the WebAssembly MVP, WebAssembly 2.0, and a growing set of newer proposals.
-//! It also supports the [Lime1](https://github.com/WebAssembly/tool-conventions/blob/main/Lime.md#lime1)
-//! interoperability target.
-//! It is designed to stay lightweight while still being practical to embed in
-//! applications, tools, and `no_std + alloc` environments.
+//! A small and portable WebAssembly interpreter.
+//!
+//! `tinywasm` passes the full WebAssembly 3.0 core testsuite and supports the
+//! [Lime1](https://github.com/WebAssembly/tool-conventions/blob/main/Lime.md#lime1)
+//! interoperability target. It is designed for embedding in applications, tools,
+//! and `no_std + alloc` environments.
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
 //!
@@ -79,7 +79,7 @@
 //!
 //! To provide imports to a module, you can use the [`Imports`] struct.
 //! This struct allows you to register custom functions, globals, memories, tables,
-//! and other modules to be linked into the module when it is instantiated.
+//! tags, and other modules to be linked into the module when it is instantiated.
 //!
 //! See the [`Imports`] documentation for more information.