1# @ajax/mesh-exec-wasm
2
3meshd's wasm executor (mesh-abi `BACKEND_WASM`), ported from alpha-rust-mesh's `mesh-host/src/wasm.rs`:
4CPU programs as WebAssembly modules running inside meshd beside the GPU backend, behind the backend
5interface of `@ajax/mesh-backend` (`mesh_wasm_backend_open`).
6
7- **Compiler** (`prepare`, on the driver's JIT thread): the manifest and abi checks, `<name>.wasm` beside
8  `program.toml`, the image hash (the PTX's when the catalog has one, else the wasm's, `param` folded in),
9  the float guard (`@ajax/wasm-float-guard`), the compile (`@ajax/wasm-interp`; with `--wasm-cache DIR`,
10  `@ajax/mesh-exec-wasm-cache`), and `mesh_rt_abi` read in a scratch instance on a zeroed mailbox.
11- **Lanes**: a running slot is `nodes` lease lanes (`@ajax/mesh-lease`), one thread and instance per
12  node, one ticket at a time; `mesh_init` / `mesh_task(op, arg)`; state lives in the view, reached
13  through the `mesh::*` imports (`@ajax/mesh-exec-wasm-imports`).
14- **Isolation**: linear memory capped at `mem_mb`, each task's epoch deadline `task_ms` (an epoch thread
15  ticks every ms while lanes run; a lockstep exchange's wait re-arms it). An overrun is `FAULT_TIME`,
16  any other trap `FAULT_TRAP | (wasmtime's trap code + 1) << 8`; the lane re-instantiates and the driver
17  fails the slot.
18- **Lifecycle**: isolated, not resident (`module_scope` is the slot itself); lanes ignore `H_BLINK`;
19  `reads_live`. Registers its cleanup at `MESH_CLEANUP_WASM`: running lanes are asked to halt.
20
21## Differences
22
23- The engine is an interpreter (`@ajax/wasm-interp`), not Cranelift. The behaviour is the same — the
24  GPUs' digests come out bit for bit (kcheck XG) — but it is about 25–35× slower than the JIT on integer
25  code. Manifests' `task_ms` budgets tuned for wasmtime (`sha256d`: 1000 ms for a 2^16-nonce chunk) can
26  be too tight here: raise them or use smaller chunks. See docs/port/wasm.md for the measurements.
27- No SIMD (wasmtime runs it for IEEE images): such an image is refused at compile ("jit").
28- Caps' name says `(wasm-interp)` where the Rust says `(wasmtime 48)`.
29- The `--wasm-cache` files hold the module's bytes (no machine code to keep).
30
31Tests: through `@ajax/mesh-wasm-programs-check` (every guest program end to end, the imports, lockstep,
32traps, interrupts, memory caps) and `@ajax/mesh-exec-wasm-cache`.