WAFER

WebAssembly Forth Engine in Rust

An optimizing Forth 2012 compiler targeting WebAssembly.

Status

WAFER is a working Forth system with an optimizing compiler. It JIT-compiles each word definition to a separate WASM module and executes via wasmtime. 392 tests passing (380 unit + 1 benchmark + 11 compliance), 0 errors on all 12 tested Forth 2012 word sets including Floating-Point.

Working features:

• Colon definitions with full control flow (IF/ELSE/THEN, DO/LOOP/+LOOP, BEGIN/UNTIL, BEGIN/WHILE/REPEAT)
• 200+ words: stack, arithmetic, comparison, logic, memory, I/O, defining words, system, exceptions, double-cell, strings, floating-point (70+ float words)
• Recursion (RECURSE), nested control structures, loop counters (I, J)
• VARIABLE, CONSTANT, CREATE, DOES>
• Number bases (HEX, DECIMAL), number prefixes ($hex, #dec, %bin)
• Pictured numeric output (<# # #S #> HOLD SIGN)
• Comments (backslash, parentheses), string output (." ...)
• Interactive REPL with line editing

Example session:

: FIB DUP 2 < IF DROP 1 ELSE DUP 1 - RECURSE SWAP 2 - RECURSE + THEN ;
: FIBS 0 DO I FIB . LOOP ;
12 FIBS CR    \ prints: 1 1 2 3 5 8 13 21 34 55 89 144

VARIABLE COUNTER  0 COUNTER !
: BUMP COUNTER @ 1 + COUNTER ! ;
BUMP BUMP BUMP COUNTER @ .  \ prints: 3

Goals

• Full Forth 2012 compliance -- all word sets, 100% test suite pass rate
• Optimizing compiler -- constant folding, inlining, peephole optimization, stack-to-local promotion
• Multi-typed stack -- type inference uses WASM's native typed stack when possible
• Self-hosting -- minimal Rust kernel (~35 primitives), everything else in WAFER Forth
• Consolidation mode -- recompile all JIT words into a single optimized WASM module

Architecture

Forth Source -> Outer Interpreter -> IR -> [Optimize] -> WASM Codegen (wasm-encoder)
                                                              |
                                                    wasmtime instantiation
                                                    (shared memory + table)

• Subroutine threading via WASM function tables and call_indirect
• JIT mode: each new word compiles to a separate WASM module linked to shared memory/globals/table
• IR-based pipeline with 6 optimization passes (peephole, constant folding, strength reduction, DCE, tail call detection, inlining) plus stack-to-local promotion and consolidation
• Dictionary: linked-list word headers in simulated linear memory

Building

cargo build --workspace

Running

# Interactive REPL
cargo run -p wafer

# Run a Forth file
cargo run -p wafer -- file.fth

# Pipe input
echo ': SQUARE DUP * ; 7 SQUARE .' | cargo run -p wafer

Testing

# All tests (392 currently passing)
cargo test --workspace

# Forth 2012 compliance dashboard
cargo test -p wafer-core --test compliance

# Optimization benchmark report
cargo test -p wafer-core --test benchmark_report -- --nocapture --ignored

# Lints
cargo clippy --workspace

Project Structure

crates/
  core/       wafer-core: dictionary, IR, codegen (wasm-encoder), outer interpreter
  cli/        wafer: CLI REPL and file execution (wasmtime, rustyline)
  web/        wafer-web: browser bindings (planned)
forth/        Standard library in WAFER Forth (planned, currently stubs)
tests/        Forth 2012 compliance suite (gerryjackson/forth2012-test-suite submodule)

Implemented Words

Core (Forth 2012 Section 6.1) -- In Progress

Category	Words
Stack	DUP DROP SWAP OVER ROT NIP TUCK 2DUP 2DROP 2SWAP 2OVER ?DUP PICK DEPTH
Arithmetic	+ - * / MOD /MOD NEGATE ABS MIN MAX 1+ 1- 2* 2/ */ */MOD M* UM* UM/MOD FM/MOD SM/REM S>D <# # #S #> HOLD SIGN
Comparison	= <> < > U< 0= 0< 0<> 0> WITHIN
Logic	AND OR XOR INVERT LSHIFT RSHIFT
Memory	@ ! C@ C! +! 2@ 2! HERE ALLOT , C, CELLS CELL+ CHARS CHAR+ ALIGNED ALIGN MOVE FILL CMOVE CMOVE>
Control	IF ELSE THEN DO LOOP +LOOP I J UNLOOP LEAVE BEGIN UNTIL WHILE REPEAT RECURSE EXIT
Defining	: ; VARIABLE CONSTANT CREATE DOES> IMMEDIATE
I/O	. U. .S CR EMIT SPACE SPACES TYPE ." S" ACCEPT
Return stack	>R R> R@
System	EXECUTE ' CHAR [CHAR] ['] DECIMAL HEX BASE STATE >IN >BODY ENVIRONMENT? SOURCE ABORT TRUE FALSE BL
Compiler	LITERAL POSTPONE [ ] EVALUATE ABORT"
Parsing	WORD FIND COUNT >NUMBER

Not Yet Implemented

12 word sets at 100% compliance: Core, Core Ext, Core Plus, Exception, Double-Number, String, Search-Order, Memory-Allocation, Programming-Tools, Facility, Locals, Floating-Point. 200+ words including VALUE, DEFER, CASE, DOES>, CATCH/THROW, double-cell arithmetic, string operations, and 70+ floating-point words.

Compliance Status

Targeting 100% Forth 2012 compliance via Gerry Jackson's test suite.

Word Set	Status
Core	100% (0 errors on test suite)
Core Extensions	100% (0 errors on test suite)
Double-Number	100% (0 errors on test suite)
Exception	100% (0 errors on test suite)
Facility	100% (0 errors on test suite)
File-Access	Pending (requires WASI)
Floating-Point	100% (0 errors on ak-fp-test)
Locals	100% (0 errors on test suite)
Memory-Allocation	100% (0 errors on test suite)
Programming-Tools	100% (0 errors on test suite)
Search-Order	100% (0 errors on test suite)
String	100% (0 errors on test suite)
Extended-Character	Pending

License

MIT OR Apache-2.0