gabagool

A WebAssembly interpreter written from scratch. It also contains a time travel debugger.

This project aims to build a fully spec-compliant, performant interpreter whose entire execution state can be serialized, suspended, and restored.

See demo

Each fork snapshots the entire WebAssembly execution state, spawns a brand new process, and resumes exactly where it left off.

See debugger demo

Every step is a full snapshot of gabagool's execution state, so you can jump to any point in history without rerunning the program

Status

gabagool speaks the WASI preview 1 spec. 38 of 43 functions are implemented. The entire WASI context (the file descriptor table, open file positions, clock state) is serializable, so snapshots taken mid-syscall restore cleanly. It is generally safe to presume the WASI implementation is solid, gabagool can run CPython compiled to WebAssembly.

gabagool is tested against the WebAssembly spec test suite. 1,960 tests pass out of 2,049 (96%). gabagool passes on arithmetic, control flow, memory, tables, globals, function references, imports/exports, and exceptions. Remaining tests involve supporting SIMD and garbage collection.

# run the core test suite
uv run download-core-tests.py
cargo t --features core-tests

# run the component test suite
# you need wasm-tools installed!
cd tests/components && bash fetch_components.sh
cargo t --features component-tests

# run an example wasm program
cargo r -- ./programs/stair_climb.wasm stair_climb 20

gabagool is not optimized and no serious profiling/benchmarking has been done. That said, the goal is to make it as performant as a pure interpreter can be. The most interesting direction is a translation phase that lowers WASM instructions into a compact intermediate representation, designed for efficient dispatch and serialization.

Reading

https://webassembly.github.io/spec/core/
bytecodealliance/wasmtime#3017
bytecodealliance/wasmtime#4002

Wasm Component Model

https://www.infoq.com/podcasts/web-assembly-component-model/
https://blog.sunfishcode.online/what-is-a-wasm-component/
https://www.fermyon.com/blog/webassembly-component-model
https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md
https://github.com/WebAssembly/component-model/blob/main/design/mvp/Binary.md
https://github.com/WebAssembly/component-model/blob/main/design/mvp/CanonicalABI.md

Copy and patch compilation

https://fredrikbk.com/publications/copy-and-patch.pdf
https://www.youtube.com/watch?v=HxSHIpEQRjs

Time travel debugging

https://awelonblue.wordpress.com/2013/01/24/exponential-decay-of-history-improved/