1# @ajax/wasm-interp
2
3A WebAssembly interpreter in C, the engine of alpha-c-mesh's wasm executor (it replaces wasmtime in the
4port of alpha-rust-mesh's `mesh-host/src/wasm.rs`).
5
6- `wasm_compile`: decode (`@ajax/wasm-decode`), validate (`@ajax/wasm-validate`), lower
7  (`@ajax/wasm-lower`). The result is immutable and shared by every thread.
8- `wasm_instantiate`: host imports resolved by module, name and signature (wasmtime's messages), store
9  limits as wasmtime's `StoreLimits` (memory bytes: past them `memory.grow` returns -1 and a larger
10  initial memory fails; tables; memories), globals, tables, element and data segments, the start
11  function. One instance per thread.
12- `wasm_call`: runs a function on an explicit value stack and frame stack (no C recursion), returning
13  WASM_NUM_OK or a trap code numbered as wasmtime's `Trap` (meshd reports it in FAULT_TRAP).
14
15The engine is meshd's: every arithmetic NaN is canonical (`@ajax/wasm-numeric`, as
16`cranelift_nan_canonicalization(true)`), no signal handlers (every memory and table access is
17bounds-checked), and epoch interruption: given an epoch counter and a deadline, a call traps with
18`interrupt` at the next loop header or function entry once the counter reaches the deadline.
19
20Proposals run: the MVP, mutable globals, sign extension, saturating float-to-int, multi-value,
21reference types, bulk memory, extended constant expressions (`WASM_F_INTERP`) — what clang's wasm32
22output uses. Not run: SIMD, relaxed SIMD, threads, multi-memory, memory64 (refused at compile).
23
24## Differences from wasmtime
25
26- An interpreter, not a JIT: much slower per instruction (see the executor's README for task rates).
27- No SIMD (wasmtime runs it for images declaring `float = "ieee"`).
28- The call stack is bounded by frames and value slots, not native stack bytes.
29
30## Tests
31
32- `tests/smoke.c`: arithmetic, recursion, a loop, memory.
33- `tests/spec.c`: every trap with its code, memory and table bounds, call_indirect, br_table,
34  multi-value, select, globals, bulk memory, table ops, canonical NaNs, imports and host traps, store
35  limits, interrupts, the start function, SIMD refused.
36- `tests/differential.c`: a C program (`tests/fixtures/prog.c`) compiled natively and to wasm32 by
37  clang (bytes in `fixtures/prog.h`) gives the same numbers for 40 seeds, integer and float.
38- `tests/fuzz.c`: 9000 mutated and random modules; none crash (run with `--profile asan`).