wasm

Validation

2026-05-17T00:33:47.893097391Z

Runtime.instantiate(bytes, …) is two passes: a parser that turns the byte stream into a typed Module representation, and a validator that walks the resulting module section-by-section before any byte of guest code is interpreted. Either step can return Left(InvalidModule(message)) — and when it does, the message is precise enough to point at the offending opcode by byte offset.

What the validator checks

For every function body, the validator runs an abstract interpreter that tracks the operand stack as a list of value types (i32 / i64 / f32 / f64 / Polymorphic), plus a control-frame stack tracking block / loop / if scopes:

Every opcode pops the right number of operands and the right value types from the abstract stack.
Every opcode pushes the result types it claims to.
Every br / br_if / br_table target index is in range, and the branch arguments (operand-stack top values) match the target’s parameter types.
call and call_indirect arguments match the callee’s signature.
local.get / local.set / local.tee indices are in range; global.set only targets mutable globals.
Memory load/store accesses use a memory index that exists in section 5.
Table accesses use a table index that exists in section 4, with the right element type.

Unreachable code after br, return, or unreachable is type-checked too — the spec requires it.

What “fail at instantiate” looks like

Bad binaries surface as Left(InvalidModule(message)) from Runtime.instantiate:

function 7: byte offset 0x1a3: i32.add expected i32 i32 on stack, found i32 f64
function 7: byte offset 0x205: br target depth 3 out of range (max 2)
function 2: byte offset 0x40: call_indirect signature mismatch — table 0 element 5 has type (i32) -> (i32), expected () -> (i32)

The byte offset is from the start of the function body, not the whole module, so it lines up directly with what wasm-objdump -d shows.

Binary sections recognised

Section	Number	What it carries
Type	1	Function signatures (`(param i32 i32) (result i32)` etc.)
Import	2	Functions, memories, globals, tables imported from the host
Function	3	Function-index → type-index mapping (signature for each body)
Table	4	Funcref tables (used by `call_indirect`)
Memory	5	Linear-memory definitions (initial + optional max pages)
Global	6	Module-level globals (mutable and immutable)
Export	7	Names exposed to the host
Start	8	A function index to run at instantiate time, before any export call
Element	9	Funcref table initializers (active, passive, and declarative kinds)
Code	10	Function bodies
Data	11	Linear-memory initializers (active and passive kinds)
DataCount	12	A `u32` = the number of data segments. Required when a function uses `memory.init` or `data.drop`. The validator cross-checks this against section 11; a mismatch is `InvalidModule`, and a function that references a `dataidx` without section 12 present is also `InvalidModule`.

Custom sections are skipped harmlessly. The name custom section is not yet used (functions appear as function <N> in error messages, not by their debug name).

LEB128

Unsigned and signed LEB128 (up to 64 bits) are implemented from scratch — no BigInteger allocation, no platform-specific decoder. The format dominates wasm’s wire encoding: every type index, function index, local index, memory immediate, and integer constant goes through it.

What validation does not catch

By design, a validator only catches violations of wasm’s static type system. It does not catch:

Trap-at-runtime errors — divide-by-zero, integer overflow on signed div, out-of-bounds memory access, indirect-call signature mismatch, branch index out of range. These surface as InvalidModule(msg) from a running function, not from instantiate.
Behavioural bugs in the guest program — infinite loops, deadlocks, wrong answers. Those are for the guest to debug, not the host.
Resource-exhaustion at instantiate — if a module claims a min-memory of 50,000 pages (≈ 3.2 GiB), the interpreter tries to allocate it. Validate the bytes against a size policy before handing them to instantiate.

Traps and errors

2026-05-17T00:33:47.893097391Z

Every public API in interp and wasi returns Either[WasmError, T]. No thrown exceptions cross the boundary. The ADT is small and exhaustive:

sealed trait WasmError

object WasmError:
  case object InvalidMagic                                          extends WasmError
  case object TypeMismatch                                          extends WasmError
  case object UnreachableExecuted                                   extends WasmError
  case object MemoryOutOfBounds                                     extends WasmError
  final case class UnknownOpcode(byte: Int)                         extends WasmError
  final case class UnknownImport(module: String, name: String)      extends WasmError
  final case class ExportNotFound(name: String)                     extends WasmError
  final case class InvalidModule(message: String)                   extends WasmError

Eight variants total. The first four are simple value objects with no payload (the variant is the diagnostic); the next four carry a payload that says where or what.

When each variant fires

Variant	Origin	Typical cause
`InvalidMagic`	parser	First four bytes aren’t `\0asm`.
`TypeMismatch`	runtime	A typed slot received a `Value` of the wrong tag — almost always an interpreter or host-binding bug, not a guest bug.
`UnreachableExecuted`	runtime	Guest executed an `unreachable` opcode. Often rustc’s panic landing pad.
`MemoryOutOfBounds`	runtime	Load, store, `memory.copy`, `memory.fill`, or `memory.init` accessed past the end of linear memory.
`UnknownOpcode(b)`	parser	The byte stream contained an opcode the interpreter doesn’t recognise.
`UnknownImport(m, n)`	instantiate	The module imports `m.n` but no `HostModule` provides it.
`ExportNotFound(name)`	runtime	`inst.invoke(name, …)` or `Wasi.run(inst, name)` looked up an export the module doesn’t have.
`InvalidModule(msg)`	validator + runtime traps	See below.

InvalidModule is a dual-purpose variant

InvalidModule(message) carries an ad-hoc string and shows up in two situations:

Validator failures. Any abstract-type-check failure during the validator’s pre-instantiate pass. The message is prefixed function <N>: byte offset 0x<hex>: <details> so it lines up with wasm-objdump -d output.
Runtime traps that aren’t memory bounds. Divide-by-zero, integer overflow on signed div_s / rem_s, i32.trunc_f32_s of NaN or out-of-range, call_indirect signature mismatch, undefined table element, br_table index past the table length.

The message names the operation that trapped. You don’t have to pattern-match it to recover, but you can grep it.

Worked example

import io.github.edadma.wasm.*
import io.github.edadma.wasm.WasmError.*

Runtime.instantiate(bytes, Seq(EnvModule.default)) match
  case Right(inst) =>
    inst.invoke("divide", Seq(I32(10), I32(0))) match
      case Right(Seq(I32(v))) => println(s"= $v")
      case Right(other)       => println(s"unexpected: $other")
      case Left(InvalidModule(msg))        => println(s"trap: $msg")
      case Left(MemoryOutOfBounds)         => println("memory bounds")
      case Left(UnreachableExecuted)       => println("unreachable")
      case Left(ExportNotFound(name))      => println(s"no export: $name")
      case Left(err)                       => println(s"other: $err")
  case Left(InvalidMagic)                  => println("not a wasm binary")
  case Left(UnknownImport(m, n))           => println(s"missing import: $m.$n")
  case Left(InvalidModule(msg))            => println(s"validator: $msg")
  case Left(err)                           => println(s"other: $err")

inst.invoke("divide", Seq(I32(10), I32(0))) returns Left(InvalidModule("i32.div_s: divide by zero")). The Right-side Seq[Value] is whatever the export’s signature says — a 0-result export returns Right(Seq.empty).

WASI exit codes

Wasi.run(inst, "_start") adds one shape on top of the Either:

Right(0) — guest’s _start returned normally, no proc_exit call.
Right(N) — guest called proc_exit(N). The host treats this as a clean exit, not a trap; whatever N is, it surfaces as Right(N).
Left(err) — anything that was a trap during execution of _start.

So Wasi.run lets a guest distinguish “I crashed” (Left) from “I exited cleanly with status N” (Right(N)) without you having to special-case proc_exit-the-syscall in your own host shim.

Tracer

2026-05-17T00:33:47.893097391Z

Tracer is the interpreter’s instrumentation hook. Every ModuleInstance.invoke and Wasi.run takes an optional tracer: Tracer = Tracer.NoOp parameter; pass anything else to receive callbacks at well-defined points during the invocation.

trait Tracer:
  def onOp(op: Int):           Unit = ()   // every opcode dispatch
  def onCall(funcIdx: Int):    Unit = ()   // wasm frame pushed
  def onHostCall(funcIdx: Int): Unit = ()  // host fn dispatched (no frame)
  def onReturn(funcIdx: Int):  Unit = ()   // wasm frame popped
  def onThrow(tagIdx: Int):    Unit = ()   // exception raised
  def onTrap(err: WasmError):  Unit = ()   // non-throw runtime error

Default methods are no-ops. The bundled Tracer.NoOp extends the trait without overriding anything; the JIT inlines its empty methods, so untraced invocations pay no per-opcode cost.

`Tracer.Counting`

The library ships a drop-in counting tracer:

import io.github.edadma.wasm.*

val tracer = Tracer.counting
inst.invoke("_start", Seq.empty, tracer) match
  case Right(_) =>
    println(s"ops:       ${tracer.ops}")
    println(s"calls:     ${tracer.calls}")      // wasm frames pushed
    println(s"hostCalls: ${tracer.hostCalls}")  // host fns dispatched
    println(s"maxDepth:  ${tracer.maxDepth}")   // peak wasm-frame depth
    println(s"throws:    ${tracer.throws}")
    println(s"traps:     ${tracer.traps}")
  case Left(err) =>
    System.err.println(s"failed: $err")

maxDepth counts wasm frames only (host calls don’t push a frame, so they don’t grow depth). A tail-recursive loop runs at constant depth regardless of iteration count — useful for confirming that a compiler emits proper return_call for recursive code.

Custom Tracer

For finer-grained tracing — opcode histograms, branch-direction profiles, per-function timing, IR-level matching against execution — implement the trait directly:

import scala.collection.mutable.ArrayBuffer

val ops = ArrayBuffer.empty[Int]

val tracer = new Tracer:
  override def onOp(op: Int): Unit = ops += op

inst.invoke("compute", Seq(I32(42)), tracer)
println(s"opcodes executed: ${ops.size}")
println(s"distinct opcodes: ${ops.toSet}")

The hooks fire in execution order. onOp runs just before the opcode dispatches; onCall runs after the new frame is pushed; onReturn runs after the frame is popped. Tail calls fire onReturn(caller) followed by onCall(callee) — the depth net change is zero, which is what Tracer.Counting.maxDepth observes.

From the CLI

wasm --trace <file> installs Tracer.counting and prints the totals to stderr after the run. See CLI → Flags for the exact output shape. Useful for quick profiling without writing any Scala.

What the tracer does NOT see

Sub-opcodes of 0xFC / 0xFD — onOp surfaces the prefix byte (0xFC / 0xFD), not the sub-opcode. If you want per-sub-op visibility, read the next byte off the function body yourself or maintain a side counter.
Block / loop / if entries — these are control-flow opcodes (0x02 / 0x03 / 0x04) and surface through onOp like everything else, but the tracer doesn’t fire a dedicated “block entered” callback. Same for br / br_if / br_table — they’re just opcodes.
Memory accesses — load/store ops fire onOp like everything else. The tracer doesn’t surface the resolved address, the touched memory, or the byte payload.
Validator-time events — the tracer is bound to runtime execution. Validation runs at Runtime.instantiate and emits errors via Left(WasmError) directly.

For all four of these cases the tracer is a hook point you’d build on top of — combine onOp with the module’s BlockInfo / function body to derive the higher-level events you need.

Lifetime + reuse

A Tracer is bound to a single invocation. Reuse across invocations is allowed if your Tracer’s internal state is reset by the caller — the runtime never touches Tracer fields between calls. Tracer.Counting instances are safe to construct once and inspect after each invoke; reset the counters yourself if you want fresh totals per call.

The runtime is single-threaded (one in-flight invoke at a time); a Tracer never sees concurrent callbacks.

Testing

2026-05-17T00:33:47.893097391Z

Unit suites

The interpreter has no test framework dependency — tests are @main-style objects with a hand-rolled PASS/FAIL runner. The same code runs on all three backends:

sbt 'interpJVM/Test/run'    # 653 interpreter tests
sbt 'interpJS/Test/run'
sbt 'interpNative/Test/run'

sbt 'wasiJVM/Test/run'      # 209 WASI tests on JVM/Native (193 on JS,
sbt 'wasiJS/Test/run'       #                   16 socket tests skipped)
sbt 'wasiNative/Test/run'

sbt 'cliJVM/Test/run'       # 19 CLI tests (JVM-only)

Total: 881 tests on JVM (653 interp + 209 wasi + 19 cli) — all three backends green for interp and wasi. Three of those are end-to-end integration tests against real rustc-built wasm32-wasip1 binaries.

Each Test/run target prints one OK <name> or FAIL <name> — <reason> line per assertion plus a final summary; the process exits non-zero if any assertion failed. Add new tests by appending test("name") { ... } calls inside the appropriate category file under interp/shared/src/test/scala/io/github/edadma/wasm/.

W3C testsuite

The official WebAssembly testsuite runs through an integrated runner — ~53,000 assertions across 142 manifests covering numerics, control flow, memory addressing, function pointers, the complete SIMD proposal, bulk memory + tables + element segments, EH and tail-call proposals, plus binary-format and UTF-8 edge cases.

./scripts/build-spec-tests.sh /path/to/wasm-testsuite     # one-time, regenerates JSON fixtures# one-time, regenerates JSON fixtures
sbt 'interpJVM/Test/runMain io.github.edadma.wasm.spec.SpecComplianceTests'

The runner consumes wast2json JSON command manifests + per-module .wasm binaries; it never parses .wast text. The script’s curated slice is the FILES=(...) array — append a manifest name and re-run to expand coverage.

See Reference → Spec compliance for current pass / fail / known-failure totals and the manifests pinned in KnownFailures.

Regenerating fixtures

The .wasm test fixtures are produced from hand-written .wat files with wat2wasm (from WABT). The committed .wasm binaries let anyone run the tests without WABT installed; Fixtures.scala is regenerated automatically on every sbt compile.

After editing any .wat:

cd interp/shared/src/test/resources/fixtures
for f in *.wat; do wat2wasm "$f" -o "${f%.wat}.wasm"; done

cd wasi/shared/src/test/resources/fixtures
for f in *.wat; do wat2wasm "$f" -o "${f%.wat}.wasm"; done

The three rustc-built fixtures are committed with their .rs source alongside as documentation; they’re rebuilt by hand when their semantics change (Cargo + the wasm32-wasip1 target).

Syscalls

2026-05-17T00:33:47.893097391Z

Twenty-nine host functions are exposed under the module name wasi_snapshot_preview1. That covers everything wasm32-wasip1 programs typically reach for: stdin/stdout, command-line args, environment variables, the clock, randomness, the filesystem (read, write, create, unlink, stat, readdir, rename, hard- and soft-link), poll-style readiness waits, and the wasi sockets surface (host-provided listening fds, accept / recv / send / shutdown).

Return shape: every wasi-preview1 syscall returns a single i32 errno (0 for success; nonzero values from the wasi-preview1 errno list — Wasi.ENOENT, Wasi.EBADF, Wasi.EFAULT, …). Output data is delivered through pointers passed by the guest into its own linear memory; the host writes the bytes there, the guest reads them back. The “Seq(I32(errno))” shape you’d see from inst.invoke reflects that single-result calling convention — the data isn’t in that Seq, it’s in memory.

Process

Syscall	Behaviour
`proc_exit(code)`	Signals the host to terminate with `code`. `Wasi.run` catches it and returns `Right(code)` instead of `Left(...)`.
`args_get(argv, buf)`	Writes `WasiContext.args` into guest memory, NUL-terminated.
`args_sizes_get(c, sz)`	Returns argc and total byte size.
`environ_get(envp, buf)`	Same shape as `args_get`, but `KEY=VALUE` pairs from `WasiContext.envs`.
`environ_sizes_get(c, sz)`	Returns environ count and total byte size.

Clock + entropy

Syscall	Behaviour
`clock_time_get(id, prec, *out)`	`id=0` → realtime nanos, `id=1` → monotonic nanos. Backed by `WasiContext.clock` (override the trait for deterministic tests). Other clock ids return `ENOTSUP`.
`random_get(buf, len)`	Writes `len` bytes of randomness to `buf`. Backed by `WasiContext.random: Int => Array[Byte]` — `SecureRandom` by default, injectable for tests.

Stdio + preopens

Syscall	Behaviour
`fd_write(fd, iovs, iovs_len, *n)`	Writes one or more iovecs. fd 1 routes to `WasiContext.stdout` (`System.out` by default), fd 2 to `WasiContext.stderr`, fd 3+ to a preopen-backed file handle.
`fd_prestat_get(fd, *out)`	wasi-libc’s startup walk asks for each preopen at fd 3, 4, … until the host returns `EBADF`. The host fills in the directory-name length here.
`fd_prestat_dir_name(fd, buf, len)`	Writes the preopen name (as UTF-8 bytes) into guest memory.

File I/O

Syscall	Behaviour
`path_open(dirfd, …, path_ptr, path_len, oflags, …, *out_fd)`	Resolves `path` against the preopen at `dirfd`, opens it according to `oflags` (`CREAT` / `EXCL` / `TRUNC` / `DIRECTORY`), and returns a new fd. Sandboxed against `..`-escape and absolute paths.
`fd_read(fd, iovs, iovs_len, *n)`	Reads into iovecs, advancing the file position. `fd 0` (stdin) dispatches through `WasiContext.stdin` — the default returns 0 bytes (EOF). `fd 1` / `fd 2` / preopen dirs / unopened fds all reject with `EBADF`.
`fd_seek(fd, offset, whence, *new_pos)`	`SEEK_SET=0`, `SEEK_CUR=1`, `SEEK_END=2`.
`fd_close(fd)`	Releases the slot in the fd table.
`fd_filestat_get(fd, *stat)`	Fills the wasi-preview1 `filestat` struct (filetype, inode placeholder, size, atim/mtim/ctim placeholders).
`fd_fdstat_get(fd, *stat)`	Filetype + fd-flags + rights.
`fd_fdstat_set_flags(fd, fdflags)`	Adjusts `APPEND`, `NONBLOCK`, `SYNC`, etc. on the fd.
`fd_sync(fd)`	Flushes any buffered writes to the host filesystem (no-op for in-memory preopens).
`fd_datasync(fd)`	Like `fd_sync` but data-only, for callers that don’t care about metadata.
`fd_advise(fd, offset, len, advice)`	Advisory POSIX `posix_fadvise`. Valid advice values 0..5 (NORMAL / SEQUENTIAL / RANDOM / WILLNEED / DONTNEED / NOREUSE) — the shim honours none of them but returns ESUCCESS so callers can ship the hint without branching. EINVAL on out-of-range advice.
`fd_allocate(fd, offset, len)`	POSIX `posix_fallocate` — ensure `[offset, offset+len)` is usable for writes. If the range extends past EOF, the file is grown with zero bytes in the gap. EBADF on stdio / preopen / unknown fd; EINVAL on negative arguments or arithmetic overflow.

Filesystem

Syscall	Behaviour
`path_filestat_get(dirfd, …, path_ptr, path_len, *stat)`	Stats `path` relative to the preopen at `dirfd` without opening it.
`path_unlink_file(dirfd, path_ptr, path_len)`	Removes a file or symlink. Already-open handles keep their cell reference (POSIX unlink-while-open). `EISDIR` for directories — use `path_remove_directory` for those (not implemented).
`path_create_directory(dirfd, path_ptr, path_len)`	Creates a directory entry. Returns `EEXIST` if anything is there already.
`path_rename(fd, old_path, new_fd, new_path)`	Moves an entry within a preopen. Cross-preopen renames return `ENOTCAPABLE`. `ENOENT` if source is missing, `EEXIST` if destination is taken.
`path_link(old_fd, …, old_path, new_fd, new_path)`	Hard link. Both paths refer to the same entry; writes through either are visible to both. Cross-preopen returns `ENOTCAPABLE`; hardlinking directories returns `EPERM`.
`path_symlink(old_path, fd, new_path)`	Creates a symlink at `new_path` whose stored target is the opaque string `old_path`. The shim does not follow symlinks during path resolution; they’re visible via `path_readlink` and surface as filetype `SYMBOLIC_LINK` (7).
`path_readlink(fd, path, buf, buf_len, *bufused)`	Reads a symlink’s target into `buf`, truncating to `buf_len` bytes. `bufused` reports the actual byte count. `EINVAL` on non-symlinks.
`fd_readdir(fd, buf, buf_len, cookie, *bytes_written)`	Enumerates directory entries. Resumable via the `cookie` for buffers smaller than the listing.

Polling

Syscall Behaviour

poll_oneoff(in, out, nsubs, *nevents) Wait for one of nsubs subscriptions to become ready. Subscriptions are 48-byte records (decoded fields userdata, eventtype, clockid/fd, timeout, precision, flags); events are 32-byte records (userdata, error, eventtype, nbytes). FD-read/FD-write subs on any valid fd report ready immediately (the InMemoryFs never blocks). CLOCK subs with timeout = 0 or an ABSTIME target already in the past fire immediately; otherwise the host actually sleeps until the earliest deadline (Thread.sleep on JVM/Native, busy-spin fallback on Scala.js). EINVAL for invalid clock ids or unknown event types (per-event), EBADF for unknown fds (per-event); EFAULT only for bounds-violating pointer args.

Syscall	Behaviour
`poll_oneoff(in, out, nsubs, *nevents)`	Wait for one of `nsubs` subscriptions to become ready. Subscriptions are 48-byte records (decoded fields `userdata`, `eventtype`, `clockid`/`fd`, `timeout`, `precision`, `flags`); events are 32-byte records (`userdata`, `error`, `eventtype`, `nbytes`). FD-read/FD-write subs on any valid fd report `ready` immediately (the InMemoryFs never blocks). CLOCK subs with `timeout = 0` or an ABSTIME target already in the past fire immediately; otherwise the host actually sleeps until the earliest deadline (`Thread.sleep` on JVM/Native, busy-spin fallback on Scala.js). EINVAL for invalid clock ids or unknown event types (per-event), EBADF for unknown fds (per-event); EFAULT only for bounds-violating pointer args.

Sockets

WASI Preview 1 sockets follow the BSD-inetd model: there is no sock_open / sock_bind / sock_listen. The host pre-binds listening sockets and hands them to the wasi program through WasiContext.sockets. The i-th listening socket is exposed at fd 3 + preopens.length + i; sock_accept resolves a listening fd and returns a fresh accepted-socket fd from the per-instance fd table. Accepted sockets also work through fd_read / fd_write (they implement FsFile under the hood).

JVM / Scala Native: HostServerSocket.bind(port) factory wraps java.net.ServerSocket (port = 0 for an OS-chosen ephemeral). Scala.js: synchronous accept can’t be expressed on the event loop, so the factory throws — a Node-backed program needs to supply its own WasiContext.ServerSocket implementation.

Syscall	Behaviour
`sock_accept(fd, fdflags, *out_fd)`	Block until a client connects to the listening fd; install the connection in the fd table and write its new fd to `*out_fd`. EBADF if the fd isn’t a listening socket.
`sock_recv(fd, ri_data, ri_data_len, ri_flags, ro_datalen, ro_flags)`	Walk the iovec table reading from an accepted socket. `ri_flags` accepts `RECV_PEEK (1)` and `RECV_WAITALL (2)` (the shim ignores both today). Returns ENOTSOCK on non-socket fds, EINVAL on unknown ri_flags bits, EFAULT on bounds-violating pointers.
`sock_send(fd, si_data, si_data_len, si_flags, *so_datalen)`	Walk the iovec table writing to an accepted socket. `si_flags` is reserved in Preview 1 — non-zero values return EINVAL.
`sock_shutdown(fd, how)`	Half-close the read side (`SD_RD = 1`), write side (`SD_WR = 2`), or both (`SD_BOTH = 3`). EINVAL on any other `how` value. Idempotent: repeated shutdowns of the same side are not an error.

Programs that issue an unimplemented syscall get back Wasi.ENOTSUP (52), which is the spec-conformant “host doesn’t support this”.

Spec compliance

2026-05-17T00:33:47.893097391Z

The interpreter has an integrated runner for the official WebAssembly testsuite. It consumes the .wast files, dispatches each assert_return / assert_trap / assert_invalid / assert_malformed command against Runtime.instantiate + inst.invoke, and tracks per-file pass / fail / skip totals.

The slice that’s wired in covers 142 manifests — numerics, conversions, control flow, memory addressing, function pointers, the complete SIMD proposal, bulk memory + tables + element segments, the EH and tail-call proposals, plus binary-format and UTF-8 edge-case manifests — over ~53,000 assertions. The parser also handles the wasm-3.0 compact-imports wire format (groups of imports sharing a module name, signaled by an empty field name plus kind byte 0x7E / 0x7F), so manifests that emit the compact form parse without special-casing.

Running it

The runner is JVM-only (it needs filesystem access for the manifest tree):

sbt 'interpJVM/Test/runMain io.github.edadma.wasm.spec.SpecComplianceTests'

Output is one line per manifest plus a totals line. Each file is tagged OK, KNOWN (failures expected and tolerated — see below), or FAIL (failures that mean a regression):

== W3C spec compliance ==
  OK    address                  259 pass,    0 fail,    1 skip
  OK    align                    119 pass,    0 fail,   46 skip
  OK    block                    208 pass,    0 fail,   15 skip
  ...
  KNOWN br_table                  24 pass,  162 fail,    0 skip
  ...
  OK    simd_i16x8_q15mulr_sat_s    30 pass,    0 fail,    0 skip
  ...
  OK    unwind                    50 pass,    0 fail,    0 skip

== Spec totals: 51714 passed, 223 failed, 1273 skipped (of 53210) ==

Exit code is non-zero iff at least one manifest is not OK or KNOWN.

How the pipeline works

The testsuite is in .wast source form. wast2json (from wabt) pre-processes each .wast into a JSON command manifest plus a directory of per-module .wasm binaries. The Scala runner consumes those — it never parses .wast text itself, so the WAT parsing burden lives entirely outside the project.

scripts/build-spec-tests.sh regenerates the manifest tree from a local checkout:

git clone https://github.com/WebAssembly/testsuite /tmp/wasm-testsuite
./scripts/build-spec-tests.sh /tmp/wasm-testsuite

The script names the curated slice explicitly (a FILES=(...) array). To add a manifest, append its name (without .wast), re-run the script, and run the spec suite to see what surfaces.

Skipped commands

Two categories of command are skipped, not run:

assert_malformed / assert_invalid with module_type: "text". wast2json couldn’t binary-encode the module (intentionally malformed text). Our interpreter only accepts binary input, so there’s nothing to test. ~285 commands across the current slice fall here.
Anything outside the dispatch ADT. register for cross-module imports, assert_unlinkable, assert_uninstantiable, etc. The current slice doesn’t emit those, but the runner skips rather than crashes if a future addition does.

Skipped commands count toward the totals line but don’t affect pass / fail status.

Known failures

9 manifests are pinned in SpecComplianceTests.KnownFailures — each one needs non-trivial implementation work beyond the surgical bug-fix pattern. They’re grouped by the feature gap they represent:

Function-references / GC proposals (not on the roadmap):

Manifest	Why
`br_table`	Module 0 uses `(ref null func)` short form (wire byte `0x63`).
`table-sub`	Same reftype short form.
`local_init`	`(ref func)` non-null short form (`0x64`).
`unreached-valid`	Function-references + typed reftype lookup.

Residual gaps after compact-imports, imported memories/tables, and cross-module register all landed (5 manifests):

names, exports, memory_grow, table_copy, and table_grow were unlocked by these features. The five remaining manifests each have a niche residual cause:

Manifest	Residual cause
`data`	Two `assert_invalid` corners the validator should catch but currently lets through
`elem`	Mostly wasm-3.0 GC reftype short form `0x40` in table sections (15 fails); 6 result-value mismatches on elem-segment edge cases
`global`	One wasm-3.0 GC reftype short form in a table section, plus 5 cascading “no current module”
`imports`	Niche import-shape mismatches
`linking`	`(ref heaptype)` short forms `0x63`/`0x64` in element segments; cascade from earlier-failed modules (function-references proposal needed)

Fixing any of these will trip an “UNEXPECTED PASSES” warning until the manifest is removed from KnownFailures.names.

What the runner caught

Triage across the initial run-up and eight coverage-expansion passes surfaced thirteen real interpreter bugs plus four feature gaps the runner unblocked:

i32.trunc_f64_s over-rejected values strictly between -2^31 and -2^31 - 1 (e.g. -2147483648.9, which truncates to INT_MIN and is in range). The range check was v < -2^31 where it should have been v <= -2^31 - 1.
MemArg.offset was an Int, so a wasm u32 offset like 0xFFFFFFFF was stored as Java -1. The Long sum addr + offset then sign-extended, turning a guaranteed-OOB load into a wrap-to-low-memory load. Widening the field to Long and masking on construction restores the trap.
align immediate validation was missing for plain load / store. The atomic path enforced align == log2(natural-width) but skipMemArg (the plain path) read the field and dropped it. A module with i32.load8_s align=2 (natural width 1, log2 = 0) instantiated successfully. Now enforced — every load/store opcode and every SIMD load/store carries an accessWidth to skipMemArg, which rejects align > log2(width).
if without else accepted mismatched params/results. The form if bt e* end (no else) has an implicit empty else-branch with type [t1*] → [t1*], so it only validates iff startTypes == endTypes. We were silently accepting cases like (if (result i32) (then (i32.const 0))) where the implicit else can’t satisfy the result. Now rejected at instantiation.
v128.const (SIMD prefix 0xFD + sub 0x0C) wasn’t accepted in const expressions — only scalar/ref const forms were recognised. (global v128 (v128.const ...)) and v128 data-segment offsets failed to parse. Const-expr reader now decodes the 16 raw bytes.
Untyped select (0x1B) rejected v128 operands. The SIMD proposal treats v128 as a numtype for the purpose of select; only the typed select t* form (0x1C) is reserved for reftypes. Numeric predicate now includes v128.
i8x16.popcnt (SIMD sub-opcode 0x62) was completely unimplemented — we had abs (0x60) and neg (0x61) but jumped to 0x63 (all_true).
i16x8.q15mulr_sat_s (SIMD sub-opcode 0x82) was completely unimplemented — only the relaxed-SIMD variant (0x111) was present. Spec semantics: (a*b + 0x4000) >> 15, saturated to i16 range.
try_table catch labels counted with the try_table on the label stack. Per the EH proposal, catch label indices count from the OUTER scope — the try_table is not yet on the label stack from the catch clause’s perspective. Both the validator (pushed the try_table frame before validating catches) and the runtime (didn’t pop the try_table label before branchTo) had matching off-by-one errors. Fix moves the pushCtrl after the catch-vector validation and adds a label-pop in the runtime’s throw-dispatch path.
Export-section validation was missing entirely. Two spec rules went unenforced: (a) export names must be unique within a module (duplicate (export "foo" ...) declarations were silently accepted, with the second shadowing the first); (b) each export’s index must be in range for its kind (a funcidx past the imports+defs count, a globalidx past the global section, etc. all instantiated). Added a single pass over module.exports at the top of Validator.validate that checks both invariants.
Name-field UTF-8 validation was missing. Every name byte sequence in the wire format (import module/field names, export names, custom-section ids, name-section subsections) must be valid UTF-8 per the spec. We were decoding via new String(bytes, "UTF-8") which silently maps malformed bytes to U+FFFD instead of rejecting. Added an RFC 3629 strict walker called from Cursor.readName that rejects stray continuations, overlong forms (0xC0/0xC1 and the overlong 3/4-byte variants), surrogate codepoints (U+D800..U+DFFF), values past U+10FFFF, lead bytes 0xF5..0xFF, and truncated multi-byte sequences. Also let the diagnostic propagate from parseCustomSection so the section name itself is enforced (was silently caught).
Binary-format strictness gaps — seven small rules our parser was lax about, surfaced together by the binary, binary-leb128, and custom manifests:
- LEB128 range checks. readU32 / readS32 / readS64 accepted oversize encodings: a 5-byte ULEB whose final byte had data bits past position 32 silently overflowed; signed forms were equally permissive on the sign-extension bits. Final byte now enforces the u32 / s32 / s64 width, with the spec’s distinct diagnostics for “integer too large” (value outside type range) and “integer representation too long” (more bytes than the type’s max).
- Section ID range. IDs outside 0..13 silently fell through case _ => (). Now rejected as “malformed section id”.
- Section order + uniqueness. Non-custom sections must appear at most once and in canonical logical order. The IDs aren’t monotonically ascending — Tag (13) is logically between Memory (5) and Global (6), and DataCount (12) is between Element (9) and Code (10). A small id → position table enforces both rules.
- Section size mismatch. c.pos = secEnd after each section silently absorbed under- or over-consumed bytes; now each non-custom section must land exactly at secEnd.
- Custom section name overruns size. A custom section with declared size 0 has no bytes for even the name-length prefix. We were reading past the section into the next one. parseCustomSection now verifies the name read didn’t overshoot secEnd.
- Too many locals. A function’s local-count groups summed past 2^32 - 1 were accepted; even a single huge group (e.g. count = 0x40000000) OOM-ed the allocation loop before the sum check could fire. Now the code reads all (count, type) groups first, sums in Long arithmetic with overflow check, then expands.
Imported globals + extended-const + relaxed const-expr were not surfaced. The parser silently skipped import kind 0x03, every const-expr accepted only a single literal opcode, and global.get in a const-expr was rejected outright. Three spec features that travel together now land as one drop: (a) GlobalImport joins FuncImport / TagImport in the module model, surfaces at instantiation via a new HostGlobal resolved against HostModule.globals, and occupies the leading slots of the unified globalidx space; (b) the const-expr reader is now a small stack-machine parser that flattens iN.add / iN.sub / iN.mul (extended-const proposal) into an expression tree the validator and runtime evaluate recursively; (c) the validator allows global.get N over any earlier-defined immutable global (wasm-3.0 relaxation), with forward-reference and mutability rejection. Active data / element segment offsets accept the same const-expr forms. The wasm-3.0 testsuite’s “compact-imports” wire format extension is a separate proposal and remains pinned.

All thirteen ship with regression tests in NumericTests, MemoryTests, MultiValueAndStartTests, SimdIntArithTests, SimdConstTests, TryTableTests, and ParserAndRuntimeTests.

Compact-imports wire format. The wasm-3.0 testsuite emits a compact import-section encoding where a regular-looking import with field_name == "" and a kind byte of 0x7E (shared-kind) or 0x7F (per-import-kind) signals that the just-read mod_name is shared across a group of sub-imports. The 0x7E form is kind sub_count (field_name desc)*; the 0x7F form is sub_count (field_name kind desc)*. The outer count field in the import-section header is the TOTAL number of imports across all groups, not the count of groups — so the parser advances i by sub_count per compact group. Without this, modules using the compact form failed at parse time with unknown import kind 0x7F. The names manifest was fully unlocked by this fix; eight other manifests gated on compact-imports now decode but still hit secondary residual gaps (imported memories / tables and cross-module register).
Imported memories + tables. Parser silently skipped import kinds 0x01 (table) and 0x02 (memory); the module then failed when an instruction referenced a memidx or tableidx with “no memory / no table”. MemoryImport and TableImport now surface in the model alongside GlobalImport; the runtime resolves them from HostModule.memories: Map[String, Memory] and HostModule.tables: Map[String, RuntimeTable] and prepends them to the live memories/tables arrays. Type checks: host’s current size ≥ module’s declared min, host’s max (if any) ≤ module’s declared max (if any), reftype match for tables, shared-vs-unshared match for memories. Four manifests fully unlocked: exports, memory_grow, table_copy, table_grow.
Cross-module register in the spec runner. wast2json emits (register "Mf" $Mf) commands that bind a previously-loaded module to a host name so later modules can import from it. The runner now tracks two registries (namedModules for action-targeted invokes, registered for import resolution); the Module command optionally binds a $name; the Register command picks a target by $name (or current) and adds it to the import registry. wrapAsHostModule builds a HostModule from a ModuleInstance‘s exports — exported functions forward through inst.invoke with traps re-thrown as ExecFail so the calling interpreter resurfaces them as Left, and memories / tables / globals forward by reference.
Shared mutable globals across module boundaries. Module storage for globals is now Array[GlobalCell] instead of Array[Value]. A GlobalCell is a tiny mutable holder; an imported mutable global installs the exporter’s cell directly into the importing module’s slot, so global.set from either side writes through the same storage — matching the wasm-3.0 spec’s “imported mutable globals are aliases for the exporter’s storage” rule. The host-import surface gains HostGlobal.live(vt, mut, cell) for sharing externally-owned cells; the existing HostGlobal(vt, mut, value) factory still works for the snapshot case (immutable globals + mutable globals the host doesn’t need to observe). ModuleInstance.exportedGlobalCell(name) is the public accessor the spec runner uses when wrapping one module’s exports as another module’s imports. The linking manifest’s mutable-global tests now exercise the shared-storage path correctly; residual linking failures are wasm-3.0 GC reftype short forms, unrelated.

Recipes

2026-05-17T00:33:47.893097391Z

Hand-written WAT, no WASI

The committed examples/hello.wasm is a hand-written WAT module that calls env.putchar 13 times. No WASI imports, no preopens needed:

sbt 'cliJVM/run examples/hello.wasm'
# Hello, world!

The matching .wat source is at examples/hello.wat. After editing, regenerate the binary with wat2wasm:

wat2wasm examples/hello.wat -o examples/hello.wasm

Freestanding C, no libc

examples/c/hello.wasm is a freestanding C program — no libc, no wasi-sdk. The source declares fd_write directly as a wasi import and defines _start as the entry point; the build is just clang --target=wasm32 -nostdlib plus wasm-ld. Useful for understanding what a wasi binary actually is once you strip the libc convenience layer off.

sbt 'cliJVM/run examples/c/hello.wasm'
# Hello from freestanding C!

The matching examples/c/hello.c source and Makefile are committed alongside; see examples/c/README.md for the build invocation.

C with wasi-libc (`<stdio.h>`, argv, exit codes)

examples/c-libc/hexdump.c is the smallest “real C program” target: it uses <stdio.h> (fopen/fread/printf/fprintf(stderr, ...)), reads its path argument from argv[1], and returns an exit code from main. The build requires wasi-sdk — the freestanding example above doesn’t, but anything that touches libc does.

# Install wasi-sdk first, then:# Install wasi-sdk first, then:
make -C examples/c-libc
sbt 'cliJVM/run --preopen /sandbox:./fixtures -- \
                examples/c-libc/hexdump.wasm /sandbox/data.bin'
# 00000000: 48 65 6c 6c 6f 0a                              |Hello.|

The .wasm is not committed (wasi-sdk isn’t free to install everywhere); see examples/c-libc/README.md for the build invocation.

Real WASI binary with a host-backed preopen

examples/rust/word_count.wasm is a rustc-built wasm32-wasip1 binary that reads a path passed as argv[1] from a wasi preopen and prints wc -lwc-style counts:

mkdir -p ./data
echo "The quick brown fox jumps over the lazy dog." > ./data/input.txt
echo "Pack my box with five dozen liquor jugs."    >> ./data/input.txt

sbt 'cliJVM/run --preopen ./data:/data examples/rust/word_count.wasm /data/input.txt'
#        2       17       86 /data/input.txt

The --preopen flag points the wasi-libc startup walk at the host’s ./data directory and tells the guest the visible name is /data. The trailing /data/input.txt is forwarded to the program as argv[1] — wasm-cli treats any positional args after the wasm file as WASI argv. From the rust binary’s perspective, /data/input.txt resolves; absolute paths outside /data don’t.

The matching examples/rust/src/main.rs source and Cargo.toml are committed; rebuild with cargo build --release --target=wasm32-wasip1 --manifest-path=examples/rust/Cargo.toml.

Real WASI binary with file writes

The test-suite fixture real_rust_filewrite.wasm writes a small file under its preopen — useful for confirming write capability against a host directory:

rm -rf /tmp/wasm-write
mkdir -p /tmp/wasm-write
sbt 'cliJVM/run --preopen /tmp/wasm-write:/sandbox \
                wasi/shared/src/test/resources/fixtures/real_rust_filewrite.wasm'
cat /tmp/wasm-write/output.txt

The path-sandbox rules apply: the rust binary asking for /sandbox/output.txt writes to /tmp/wasm-write/output.txt; the same binary asking for ../escape returns ENOTCAPABLE.

Native CLI binary

cliNative builds a standalone Scala Native binary — no JVM startup overhead, useful when you want to run wasm in a shell pipeline:

sbt cliNative/nativeLink
./cli/native/target/scala-3.8.3/wasm-cli-out \
    --preopen /tmp/sandbox:/sandbox \
    real_rust_fileread.wasm

The Scala Native build uses the same HostPreopen.fromDir shape as the JVM build but backs it with java.nio.file (via Scala Native’s JVM-compatibility layer).

Scala.js CLI (Node.js)

sbt’s command-line parser doesn’t forward positional args to scalajs‘s run task, so the JS CLI runs through Node directly:

sbt cliJS/fastLinkJS
node cli/js/target/scala-3.8.3/wasm-cli-fastopt/main.js \
     --preopen /tmp/sandbox:/sandbox \
     real_rust_fileread.wasm

The Scala.js build backs HostPreopen.fromDir with Node’s fs.*Sync APIs. Same trait surface, different syscalls underneath.

Inspecting a module without running it

--list-exports prints every exported function without instantiating:

sbt 'cliJVM/run --list-exports my-module.wasm'

Useful when picking an --invoke target, or when sanity-checking that a build pipeline produced the symbols you expect.

Quickstart

2026-05-17T00:33:47.893097391Z

This walkthrough shows the three things you’ll do with the library 95 % of the time: instantiate a non-WASI module and invoke a function, run a WASI command-mode binary, and customize the host environment.

1. Instantiate and invoke

The minimal case — a module with no WASI imports, exporting one function you’d like to call:

import io.github.edadma.wasm.*

val bytes: Array[Byte] = /* contents of a .wasm file */

Runtime.instantiate(bytes, Seq(EnvModule.default)) match
  case Right(inst) =>
    inst.invoke("fact", Seq(I32(5))) match
      case Right(Seq(I32(v))) => println(s"fact(5) = $v")
      case Right(other)       => println(s"unexpected result: $other")
      case Left(err)          => println(s"trap: $err")
  case Left(err) =>
    println(s"failed to instantiate: $err")

EnvModule.default ships a single env.putchar(i32) → () import that writes the low byte to System.out. Modules compiled by lightweight toolchains (hand-written .wat, Emscripten with -s STANDALONE_WASM=0) often expect it; modules that don’t import env.putchar are unaffected.

Runtime.instantiate validates the binary before any code runs. Bad modules return Left(InvalidModule("function <N>: byte offset 0x<hex>: <details>")) — see Concepts → Validation for what the validator checks.

2. Run a WASI command-mode binary

For real wasm32-wasip1 binaries — anything compiled by rustc, zig, or Clang’s WASI sysroot — you want Wasi.run, which handles _start, command-line args, environment variables, preopens, and proc_exit for you:

import io.github.edadma.wasm.*
import io.github.edadma.wasm.wasi.{Wasi, WasiContext, HostPreopen}

val bytes: Array[Byte] = /* a rustc-built wasm32-wasip1 binary */

val ctx = WasiContext.default.copy(
  args     = Seq("myprog", "--flag", "value"),
  envs     = Seq("HOME" -> "/root", "LANG" -> "C.UTF-8"),
  preopens = Seq(HostPreopen.fromDir("/var/data", "/data")),
)

Runtime.instantiate(bytes, Seq(EnvModule.default, Wasi.preview1(ctx))) match
  case Right(inst) =>
    Wasi.run(inst, "_start") match
      case Right(code) => sys.exit(code)
      case Left(err)   => System.err.println(s"runtime error: $err"); sys.exit(1)
  case Left(err) =>
    System.err.println(s"instantiate failed: $err"); sys.exit(1)

Clean exit returns Right(0). A proc_exit(N) call returns Right(N). A trap returns Left(WasmError). No thrown exceptions cross the API boundary.

3. Customize the host environment

WasiContext is a plain case class — copy-and-modify the bits you care about:

import io.github.edadma.wasm.wasi.{WasiContext, HostPreopen}
import WasiContext.Preopen

val ctx = WasiContext.default.copy(
  args     = Seq("prog", "input.txt"),
  envs     = Seq("PATH" -> "/usr/bin"),
  // Three preopen flavours, mix and match:
  preopens = Seq(
    HostPreopen.fromDir("/tmp/sandbox", "/sandbox"),                    // real host directory
    Preopen.inMemory("/cfg",                                            // in-memory map
      Map("settings.toml" -> "verbose = true\n".getBytes)),
    Preopen.named("/devices"),                                          // probe-only stub
  ),
  // Inject your own clock or randomness for deterministic tests:
  clock    = WasiContext.systemClock,                                   // or your own `Clock` impl
  random   = (n: Int) => Array.fill(n)(0x42.toByte),                    // not random at all — fine for tests
)

HostPreopen.fromDir is sandboxed by construction: absolute paths from the guest, NUL bytes, and .. segments are all rejected at the path_open boundary. See WASI → Preopens for the full sandboxing model.

Where to go next

Concepts → ModuleInstance — the full public API on what Runtime.instantiate returns.
Concepts → Validation — what the validator catches and what it doesn’t.
Concepts → Host imports — wire your own functions into a module.
WASI → WasiContext — the configuration record Wasi.preview1 takes.
WASI → Syscalls — the 29 syscalls implemented and their semantics.
CLI — when you want a runner more than a library.
Reference → Errors — every WasmError variant and what causes it.

Preopens

2026-05-17T00:33:47.893097391Z

A WASI program can’t open files by absolute path. wasi-libc walks the fds 3, 4, … at program startup, asks the host for the name of each preopened directory, and builds an internal name → fd map; everything later that calls open("/sandbox/hello.txt", …) is rewritten by libc into path_open(dirfd=3, "hello.txt", …). The host never sees an absolute path from the guest.

WasiContext.preopens: Seq[Preopen] is the list the host advertises. The i-th entry shows up at fd 3 + i. Three factories:

Factory	Backing	What it does
`Preopen.named(name)`	none	Advertises the name; every `path_open` against it returns `ENOTCAPABLE`.
`Preopen.inMemory(name, files)`	`Map[String, Array[Byte]]`	Full read/write semantics — `CREAT`, `EXCL`, `TRUNC`, unlink, mkdir, readdir. What the test suite uses.
`HostPreopen.fromDir(hostPath, virtualName)`	real on-disk directory	Sandboxed access to an actual host directory. JVM and Scala Native use `java.nio.file` + `FileChannel`; Scala.js uses Node’s `fs.*Sync`.

Programs see the same wasi-preview1 surface no matter which kind is in play — only the host distinguishes them.

Named preopens

val ctx = WasiContext.default.copy(
  preopens = Seq(Preopen.named("/etc"), Preopen.named("/var")),
)

Preopen.named is the minimum surface: it makes fd_prestat_get(3) succeed and report the name, and that’s it. path_open against fd 3 returns ENOTCAPABLE (not ENOENT — the distinction matters: ENOENT says “no such path”, ENOTCAPABLE says “you can’t even ask through this preopen”). It’s the right choice when you want to expose a directory’s existence to libc startup probing without giving the guest the capability to read it.

In-memory preopens

val files = Map(
  "hello.txt"        -> "Hello from memory\n".getBytes,
  "config/site.toml" -> "title = \"test\"\n".getBytes,
)

val sandbox = Preopen.inMemory("/sandbox", files)

val ctx = WasiContext.default.copy(preopens = Seq(sandbox))

The backing Map[String, Array[Byte]] is mutable behind the scenes — path_open(..., OFLAGS_CREAT, ...) adds new entries, path_unlink_file drops them, OFLAGS_TRUNC zeroes the bytes. After the guest runs, the concrete InMemoryPreopen returned by Preopen.inMemory exposes bytesOf(path) so tests can inspect what was written:

val sandbox = Preopen.inMemory("/sandbox")              // empty to start
// ... run the guest, which writes "output.bin" ...
sandbox.bytesOf("output.bin")  // → Some(Array[Byte](...))

In-memory preopens never touch the host filesystem and never block on I/O — they’re the right choice for unit tests, fuzzing, and any scenario where guest writes shouldn’t escape the process.

Host-directory preopens

import io.github.edadma.wasm.wasi.HostPreopen

val ctx = WasiContext.default.copy(
  preopens = Seq(HostPreopen.fromDir("/var/data", "/data")),
)

HostPreopen.fromDir(hostPath, virtualName) resolves hostPath to a real Path and uses it as the root. Every guest path is resolved against it through the wasi-preview1 path-sandbox rules:

Absolute paths from the guest are rejected outright (would-be roots like /etc/passwd never reach the host filesystem).
NUL bytes in the guest-supplied path are rejected (defense against malformed strings).
.. segments that would escape the root after normalization are rejected with ENOTCAPABLE.
Symlinks inside the directory are followed by the host filesystem; following one out of the root re-triggers the path-escape check on the resolved target.

The three backends (JVM, Native, JS) differ only in how they implement path_open and the read/write/stat/readdir syscalls under the hood. The trait surface is identical; the path-sandbox rules are enforced before any platform-specific code runs.

Picking a preopen kind

HostPreopen.fromDir — production use. The guest gets real persistent storage in a controlled subtree of the host filesystem.
Preopen.inMemory — tests and any case where the guest’s writes need to be inspectable from Scala without crossing the filesystem.
Preopen.named — when a guest probes preopens for capability discovery and you want to expose the name but not the contents.

You can mix them freely. The order of preopens in WasiContext determines the fd ordering — preopen [0] is fd 3, preopen [1] is fd 4, and so on.

The `Preopen` trait surface

If the three factories don’t fit and you want to implement a custom preopen — say, an S3-backed read-only mount or an HTTP-fetching probe — you can subclass WasiContext.Preopen directly:

trait Preopen:
  /** wasi-visible directory name (what userspace sees through `fd_prestat_dir_name`). */
  def name: String

  /** Open a path relative to this preopen. Called from `path_open`.
    * Default returns Left(ENOTCAPABLE). */
  def open(path: String, oflags: Int, fdflags: Int): Either[Int, Wasi.FsFile]

  /** Stat a path WITHOUT opening it. Called from `path_filestat_get`.
    * Right(size) for an existing regular file; Left(errno) otherwise.
    * Default returns Left(ENOTCAPABLE). */
  def statPath(path: String): Either[Int, Long]

Three things to know:

Wasi.FsFile is the file-handle trait — read / write / seek / size / tell / close. The shim never sees a Java File or a Path; it talks to your FsFile. The InMemoryPreopen and HostBackedPreopen impls are reference implementations you can read in the source.
Several methods are private[wasi] (unlinkPath, mkdir, readdir, filetypeOf). External impls inherit their ENOTCAPABLE / empty defaults but can’t override them — write/enumerate semantics for custom preopens are intentionally limited to what the trait surface above allows. If you genuinely need to override one of those, the customization belongs upstream as a new factory rather than as a downstream subclass.
oflags / fdflags are passed through verbatim. The OFLAGS_CREAT (1), OFLAGS_DIRECTORY (2), OFLAGS_EXCL (4), OFLAGS_TRUNC (8) bits and the FDFLAGS_* set are documented in wasi-preview1. Read-only impls ignore them.

For the common case — read/write semantics over an in-memory map, or sandboxed access to a real directory — reach for Preopen.inMemory and HostPreopen.fromDir instead. They cover what most callers need.

Opcodes

2026-05-17T00:33:47.893097391Z

The interpreter implements every WebAssembly Core opcode plus the sign-extension proposal, the full bulk-memory proposal, non-trapping float-to-int (trunc_sat_*), the reference-types proposal (funcref, externref, ref.null / ref.is_null / ref.func, table.get / table.set / table.size / table.grow / table.fill, typed select t*), the multi-memory proposal (every memory opcode now carries a memidx; modules may declare more than one linear memory, with a parallel HostFuncMulti surface for host functions that need to reach beyond memidx 0), and the full SIMD proposal (V128 value type plumbed end-to-end; all ~236 opcodes under the 0xFD prefix — v128.const, the 14 loads + 8 stores including load*_lane / store*_lane, lane access, integer + float arithmetic, shifts, min/max, bitwise + reductions, comparisons, narrow / extend / extadd_pairwise / extmul, float ↔ int conv, demote / promote, and i32x4.dot_i16x8_s). That’s enough to run real wasm32-wasip1 binaries produced by rustc end-to-end, and to host the full sysl standard-library test suite end-to-end as sysl’s wasm32-WASI backend.

Numeric (all four scalar types)

Every i32 / i64 / f32 / f64 opcode:

Constants — const for each type.
Comparisons — signed and unsigned for ints (lt_s, lt_u, le_s, …); ordered for floats (lt, le, gt, ge, eq, ne).
Arithmetic — add, sub, mul, div_s / div_u (ints), div (floats), rem_s / rem_u.
Bitwise — and, or, xor (ints).
Shifts — shl, shr_s, shr_u, rotl, rotr (ints).
Conversion — every cross-type cast in the Core spec (i32.wrap_i64, i64.extend_i32_s/_u, i32.trunc_f32_s/_u/…, f32.convert_i32_s/_u/…, f32.demote_f64, f64.promote_f32).
Reinterpretation — i32.reinterpret_f32, f64.reinterpret_i64, etc. (bit-level recasts that don’t change the value’s bits).

IEEE-754 results are deterministic across JVM, Scala.js, and Scala Native — including NaN bit patterns, signed-zero, and subnormal edges.

Sign-extension proposal

i32.extend8_s, i32.extend16_s, i64.extend8_s, i64.extend16_s, i64.extend32_s. Lifts a narrow signed value into the full operand-stack width. Required by rustc-built binaries.

Non-trapping float-to-int

The eight trunc_sat_* sub-opcodes under the 0xFC prefix (sub-opcodes 0..7):

i32.trunc_sat_f32_s / _u, i32.trunc_sat_f64_s / _u
i64.trunc_sat_f32_s / _u, i64.trunc_sat_f64_s / _u

Where trunc_f32_s of NaN or out-of-range traps, trunc_sat_f32_s returns 0 for NaN and saturates at the type’s MIN_VALUE / MAX_VALUE for out-of-range. Required by rustc binaries built with -C target-feature=+nontrapping-fptoint (now the default on stable).

Variables

local.get, local.set, local.tee, global.get, global.set. Mutable and immutable globals are both supported; global.set on an immutable global is caught by the validator.

Control flow

block, loop, if / else / end, br, br_if, br_table, return, call, call_indirect, unreachable, nop.

Multi-value blocks, loops, and ifs are supported — block parameters get re-fed on br to a loop, br_if carries multi-result values, etc.

Tail calls

The tail-call proposal is supported: return_call funcidx (0x12) and return_call_indirect typeidx tableidx (0x13) replace the current call frame instead of growing the call stack. The callee’s results must equal the current function’s results — the validator enforces this. Frame-reuse is observable: deeply recursive tail calls (the test suite exercises 100k iterations) run in constant frames memory.

Exception handling

Both forms of the exception-handling proposal are supported end-to-end — the legacy “phase 3” form (try / catch / catch_all / delegate / rethrow, what wasmtime + V8 + SpiderMonkey + wat2wasm‘s --enable-exceptions emit today) and the modern try_table form (0x1F plus an exnref value type and throw_ref, the phase-4 redesign that’s standardising now).

Legacy form

try blocktype (0x06) — open a block-shaped region whose body can be guarded by one or more catch clauses, a single catch_all, or a single delegate.
catch tagidx (0x07) — handle an exception whose tag matches tagidx; the tag’s payload params are pushed onto the operand stack at handler entry.
catch_all (0x19) — handle any exception regardless of tag; no payload is pushed.
delegate labelidx (0x18) — terminator that replaces end; on a throw out of the try body, re-fire the exception at the named outer label (must be a try or the function frame).
throw tagidx (0x08) — pop the tag’s payload params off the operand stack and raise the matching exception.
rethrow labelidx (0x09) — re-raise the exception caught by the named outer catch handler. Only valid inside a catch / catch_all clause.

A catch / catch_all arrived at by normal fall-through (i.e. the try body completed without throwing) is dead code; control jumps past the entire try/catch chain.

Modern `try_table` form

A single new opcode replaces the try / catch / delegate / rethrow cluster. The handler vector is parsed up front as an immediate, then the body runs as a regular block.

try_table blocktype vec(catch-clause) (0x1F) — open a block-shaped region. Each catch clause selects a tagidx (or wildcard) and a labelidx to branch to when a matching throw escapes the body.
throw_ref (0x0A) — pop an exnref and re-raise the carried exception. Replaces rethrow.
exnref valtype (wire byte 0x69) — carries a caught exception. Bound by catch_ref / catch_all_ref handler clauses; consumed by throw_ref. Locals, params, results, and blocktypes may all be exnref.

The four catch-clause shapes (encoded as a byte before each clause’s immediates):

Byte	Clause	Branch arity at target
`0x00`	`catch tagidx labelidx`	tag’s payload params
`0x01`	`catch_ref tagidx labelidx`	tag’s payload params + `exnref`
`0x02`	`catch_all labelidx`	(empty)
`0x03`	`catch_all_ref labelidx`	`exnref`

labelidx is counted with the try_table frame on the control stack — labelidx 0 names the try_table itself, 1 the next outer block, etc. On a matching throw delivery, the runtime trims the operand stack to the try_table‘s entry height, pushes the handler’s declared payload, then performs the equivalent of br labelidx. Clauses are scanned in declared order; the first match wins.

Memory

Load/store — every width variant: i32.load, i32.load8_s/_u, i32.load16_s/_u, i64.load, i64.load8_s/…/load32_s/_u, f32.load, f64.load, plus all matching stores.
Sizing — memory.size and memory.grow. The optional max from section 5 is honoured: grow past it returns -1 rather than expanding.
Bulk-memory — the full proposal, all seven ops under the 0xFC prefix:
- memory.copy (sub 0x0A), memory.fill (sub 0x0B).
- memory.init (sub 0x08), data.drop (sub 0x09).
- table.init (sub 0x0C), elem.drop (sub 0x0D), table.copy (sub 0x0E).
memory.init / table.init copy from passive data / element segments; data.drop / elem.drop mark a segment as zero-length (idempotent). Active segments are still initialised at instantiation and then marked dropped automatically — subsequent *.init with n > 0 traps, matching wasmtime / V8 / wabt semantics.

Passive vs active data + element segments

Section 11 (data) and section 9 (element) carry sealed-trait segment kinds. Active segments behave as before (copied at instantiation). Passive segments stay addressable by dataidx / elemidx until the matching .drop. Declarative element segments pre-declare funcrefs for ref.func. Element-expression-bearing forms (flags 4..7) parse ref.null and ref.func as their constant expressions; segments may carry either funcref or externref payloads.

Reference types

Funcref + externref ride on a small set of new opcodes:

ref.null (0xD0 + reftype byte) — typed null reference. ref.null func produces a null funcref; ref.null extern a null externref.
ref.is_null (0xD1) — pop a reference, push 1 if it’s a ref.null, else 0.
ref.func (0xD2 + funcidx LEB) — produce a non-null funcref pointing at the named function. The validator enforces that the funcidx is declared — i.e. it appears in an export, in start, or in any element segment. Body-only references would be circular and so don’t count.
table.get (0x25 + tableidx LEB), table.set (0x26 + tableidx LEB) — read / write a table slot. Operand type is the table’s reftype.
table.size (0xFC sub 16 + tableidx LEB), table.grow (0xFC sub 15 + tableidx LEB), table.fill (0xFC sub 17 + tableidx LEB) — runtime-side table resize + range fill, with a typed fill value.

Externref slots carry an opaque host AnyRef. Wasm code can only move them around (table.{get,set}, local.{get,set}, global.{get,set}, ref.is_null); inspection happens host-side via the public API. The host hands them in as Value.RefExtern(yourObject) and pulls them back as the same identity.

call_indirect is now spec-restricted to funcref tables (an externref table can’t carry callable funcrefs); the validator rejects mismatches before code runs.

Tables + functions

Section 4 funcref + externref tables. call_indirect does a signature check at the call site against the operand-stack types and the target function’s declared type; a mismatch traps with Left(InvalidModule("call_indirect type mismatch")).

Stack

drop, select. Two select forms:

Untyped select (0x1B) — operand types are inferred. Spec-restricted to numeric value types when reference types are present; a reftype operand is rejected at validation with a “use select t*” diagnostic.
Typed select t* (0x1C) — explicit operand type, encoded as 0x1C u32:count valtype[count] with count == 1 (multi-value select isn’t enabled by any shipped proposal). Required for funcref / externref operands; also accepts the four numeric scalars.

SIMD

The WebAssembly SIMD proposal adds ~236 opcodes under the 0xFD prefix and a new V128 value type (16 raw bytes, lane interpretation chosen per-opcode). The full surface is implemented.

The `V128` value type (host side)

final case class V128(bits: Array[Byte]) extends Value

A SIMD value is a raw 16-byte buffer; the lane shape (i8x16, i16x8, i32x4, i64x2, f32x4, f64x2) is not carried on the value — it’s chosen per-opcode at use time. Same 16 bytes, six possible interpretations. The interpreter enforces bits.length == 16 on every constructed value.

Byte order is little-endian per the spec: lane 0 of any shape starts at byte 0, the low byte of each lane comes first, and v128.load reads bytes in memory order into the same positions. So to build a V128 from four i32 lanes:

def i32x4(a: Int, b: Int, c: Int, d: Int): V128 =
  val buf = new Array[Byte](16)
  val bb  = java.nio.ByteBuffer.wrap(buf).order(java.nio.ByteOrder.LITTLE_ENDIAN)
  bb.putInt(a).putInt(b).putInt(c).putInt(d)
  V128(buf)

inst.invoke("dot", Seq(i32x4(1, 2, 3, 4), i32x4(5, 6, 7, 8)))

To inspect a V128 result from invoke:

inst.invoke("compute") match
  case Right(Seq(V128(bs))) =>
    val bb    = java.nio.ByteBuffer.wrap(bs).order(java.nio.ByteOrder.LITTLE_ENDIAN)
    val lanes = Array(bb.getInt, bb.getInt, bb.getInt, bb.getInt)
    println(lanes.mkString("[", ", ", "]"))
  case _ => ???

The test suite’s TestSupport.simd object has helpers (fromI8, fromI16, fromI32, fromI64, fromF32, fromF64) for each lane shape — they’re test-scope but easy to copy if your host code needs the same builders.

V128 equality: the case class derives equals from Array[Byte] reference equality (Scala’s Array doesn’t define structural equals). So V128(a) == V128(b) is true only if a eq b. Compare the bytes directly if you want value equality.

Foundations

V128 value type (wire byte 0x7B). First-class in function params, results, locals, globals, and blocktypes. Locals zero-init to 16 zero bytes.
v128.const (0xFD 0x0C + 16 raw little-endian bytes). The wat-side annotations (i32x4 1 2 3 4, i16x8 ..., etc.) are text-form only; the binary just sees 16 opaque bytes.
0xFD prefix dispatch — the SIMD sub-opcode is LEB-encoded.

Tests cover raw byte round-trips, parameter / local / block-result plumbing, zero-init, and the wat-form lane-annotation equivalence (v128.const i8x16 and v128.const i16x8 of the same byte payload produce identical V128 values).

Loads + stores

Every load is [i32 addr] → [v128]; the store is [i32 addr, v128 value] → []. All ops carry a multi-memory-shaped memarg (the alignment LEB’s bit 6 flags an optional memidx LEB; offset follows).

Opcode	Sub	What it does
`v128.load`	`0x00`	Full 16-byte little-endian load.
`v128.load8x8_s` / `_u`	`0x01` / `0x02`	Read 8 source bytes, widen each (sign / zero) into 8 i16 lanes.
`v128.load16x4_s` / `_u`	`0x03` / `0x04`	Read 4 source i16s, widen each into 4 i32 lanes.
`v128.load32x2_s` / `_u`	`0x05` / `0x06`	Read 2 source i32s, widen each into 2 i64 lanes.
`v128.load8_splat`	`0x07`	Read 1 byte, broadcast across all 16 lanes.
`v128.load16_splat`	`0x08`	Read 2 bytes, broadcast across all 8 i16 lanes.
`v128.load32_splat`	`0x09`	Read 4 bytes, broadcast across all 4 i32 lanes.
`v128.load64_splat`	`0x0A`	Read 8 bytes, broadcast across all 2 i64 lanes.
`v128.store`	`0x0B`	Full 16-byte little-endian store.
`v128.load32_zero`	`0x5C`	Read 4 bytes into lane 0; zero the remaining 12.
`v128.load64_zero`	`0x5D`	Read 8 bytes into lane 0; zero the remaining 8.

Out-of-bounds (addr + offset + width past memory end) traps with MemoryOutOfBounds, same shape as the scalar memory ops.

Lane access

Every “build / inspect / rearrange a v128 lane-by-lane” surface lives here. Lane shapes — i8x16, i16x8, i32x4, i64x2, f32x4, f64x2 — pick the lane width (1/2/4/8 bytes) and the count (16/8/4/2 lanes). Lane immediates are validated < lane_count at compile time.

Opcode	Sub	What it does
`i8x16.shuffle`	`0x0D`	16-byte laneidx immediate (each `< 32`); each result lane is `a[c]` if `c<16` else `b[c-16]`.
`i8x16.swizzle`	`0x0E`	Dynamic shuffle. `s` (top) is the index vector, `v` (below) is the source. Result lane `i` = `v[s[i]]` if `s[i] < 16` else `0`.
`i8x16.splat`	`0x0F`	Broadcast the low 8 bits of an i32 to 16 lanes.
`i16x8.splat`	`0x10`	Broadcast the low 16 bits LE to 8 lanes.
`i32x4.splat`	`0x11`	Broadcast 4 LE bytes to 4 lanes.
`i64x2.splat`	`0x12`	Broadcast 8 LE bytes to 2 lanes.
`f32x4.splat`	`0x13`	Broadcast the IEEE-754 bit pattern of an f32 to 4 lanes.
`f64x2.splat`	`0x14`	Broadcast the IEEE-754 bit pattern of an f64 to 2 lanes.
`i8x16.extract_lane_s` / `_u`	`0x15` / `0x16`	Read 1 byte at lane (signed / zero extended to i32).
`i8x16.replace_lane`	`0x17`	Write the low byte of an i32 at the lane.
`i16x8.extract_lane_s` / `_u`	`0x18` / `0x19`	Read 2 LE bytes at lane (signed / zero extended to i32).
`i16x8.replace_lane`	`0x1A`	Write the low 16 bits LE at the lane.
`i32x4.extract_lane`	`0x1B`	Read 4 LE bytes at lane → i32.
`i32x4.replace_lane`	`0x1C`	Write 4 LE bytes at lane.
`i64x2.extract_lane`	`0x1D`	Read 8 LE bytes at lane → i64.
`i64x2.replace_lane`	`0x1E`	Write 8 LE bytes at lane.
`f32x4.extract_lane`	`0x1F`	Read 4 LE bytes at lane → f32 (raw IEEE-754 bits, no NaN canonicalisation).
`f32x4.replace_lane`	`0x20`	Write 4 LE bytes at lane.
`f64x2.extract_lane`	`0x21`	Read 8 LE bytes at lane → f64.
`f64x2.replace_lane`	`0x22`	Write 8 LE bytes at lane.

extract_lane / replace_lane carry a 1-byte lane immediate after the sub-opcode; i8x16.shuffle carries a 16-byte laneidx vector. splat and swizzle have no immediate beyond the sub-opcode.

Integer arithmetic

Lane-wise integer arithmetic across every integer shape. Plain add / sub / mul wrap modulo 2^lane_width; _sat_s / _sat_u clamp at the signed / unsigned bounds; avgr_u is the rounding unsigned average (a + b + 1) / 2. No i8x16.mul in the spec, no saturating variants past i16x8, no avgr_u past i16x8. All ops have no immediate.

Opcode	Sub	What it does
`i8x16.abs`	`0x60`	`abs(MinValue)` wraps to `MinValue` (overflow mod 2^8).
`i8x16.neg`	`0x61`	`neg(MinValue)` wraps likewise.
`i8x16.add`	`0x6E`	Wraps mod 256 per lane.
`i8x16.add_sat_s` / `_u`	`0x6F` / `0x70`	Clamps to `[-128, 127]` / `[0, 255]`.
`i8x16.sub`	`0x71`	Wraps mod 256.
`i8x16.sub_sat_s` / `_u`	`0x72` / `0x73`	Clamps to the signed / unsigned lane bounds.
`i8x16.avgr_u`	`0x7B`	`(a + b + 1) / 2` per lane (rounds up).
`i16x8.abs` / `neg`	`0x80` / `0x81`	Same shape as `i8x16`.
`i16x8.add` / `add_sat_s` / `add_sat_u`	`0x8E` / `0x8F` / `0x90`	Wrap / clamp to `[-32768, 32767]` / `[0, 65535]`.
`i16x8.sub` / `sub_sat_s` / `sub_sat_u`	`0x91` / `0x92` / `0x93`	Wrap / clamp.
`i16x8.mul`	`0x95`	Low 16 bits of the full-width product.
`i16x8.avgr_u`	`0x9B`	`(a + b + 1) / 2` per lane unsigned.
`i32x4.abs` / `neg`	`0xA0` / `0xA1`	`abs(Int.MinValue)` wraps.
`i32x4.add` / `sub` / `mul`	`0xAE` / `0xB1` / `0xB5`	Wrap mod 2^32; `mul` is the low 32 bits.
`i64x2.abs` / `neg`	`0xC0` / `0xC1`	`abs(Long.MinValue)` wraps.
`i64x2.add` / `sub` / `mul`	`0xCE` / `0xD1` / `0xD5`	Wrap mod 2^64.

Sub-opcodes ≥ 0x80 encode as 2-byte LEBs in the binary; wat2wasm emits the right shape, and the dispatch’s LEB decoder handles either width transparently.

Shifts + min/max

Lane-wise shifts (shl, shr_s, shr_u) on all four integer shapes, plus per-lane signed and unsigned min/max on i8x16, i16x8, i32x4 (the spec excludes i64x2.min/max). Shifts pop the i32 count from the operand stack — it’s not an immediate — and the spec takes count mod lane_width, so e.g. i8x16.shl(_, 8) is the identity.

Opcode	Sub	What it does
`i8x16.shl`	`0x6B`	Shift left; count mod 8.
`i8x16.shr_s` / `_u`	`0x6C` / `0x6D`	Arithmetic / logical right shift; count mod 8.
`i8x16.min_s` / `_u`	`0x76` / `0x77`	Per-lane signed / unsigned minimum.
`i8x16.max_s` / `_u`	`0x78` / `0x79`	Per-lane signed / unsigned maximum.
`i16x8.shl`	`0x8B`	Shift left; count mod 16.
`i16x8.shr_s` / `_u`	`0x8C` / `0x8D`	Arithmetic / logical right shift; count mod 16.
`i16x8.min_s` / `_u`	`0x96` / `0x97`	Per-lane signed / unsigned minimum.
`i16x8.max_s` / `_u`	`0x98` / `0x99`	Per-lane signed / unsigned maximum.
`i32x4.shl`	`0xAB`	Shift left; count mod 32.
`i32x4.shr_s` / `_u`	`0xAC` / `0xAD`	Arithmetic / logical right shift; count mod 32.
`i32x4.min_s` / `_u`	`0xB6` / `0xB7`	Per-lane signed / unsigned minimum.
`i32x4.max_s` / `_u`	`0xB8` / `0xB9`	Per-lane signed / unsigned maximum.
`i64x2.shl`	`0xCB`	Shift left; count mod 64.
`i64x2.shr_s` / `_u`	`0xCC` / `0xCD`	Arithmetic / logical right shift; count mod 64.

The signed vs unsigned distinction matters at the lane width: byte 0xFF is -1 signed but 255 unsigned, so i8x16.shr_s of it stays -1 while i8x16.shr_u of it becomes 0x7F; i8x16.min_s picks -1 as the minimum but i8x16.min_u picks 0.

Float arithmetic

Lane-wise IEEE-754 arithmetic across f32x4 and f64x2. Rounding (ceil, floor, trunc, nearest) and abs / neg / sqrt are unary; add / sub / mul / div and min / max / pmin / pmax are binary. All ops have no immediate.

abs / neg are bit-level (clear / flip the sign bit) and preserve NaN payloads exactly — useful for round-tripping signaling NaNs. Arithmetic ops produce an NaN when any operand is NaN; the bit pattern follows the same implementation-defined rule as scalar f32.add / f64.add (in practice the JVM’s canonical 0x7FC00000 / 0x7FF8000000000000).

min and max use IEEE-754 semantics: NaN-involving inputs produce NaN, and -0 orders below +0. pmin(a,b) and pmax(a,b) follow the spec’s compare-then-pick formula — pmin = if b<a then b else a, pmax = if a<b then b else a — which means a NaN-involving compare always returns false, so a is picked. That gives pmin / pmax a different NaN behaviour from min / max: a non-NaN a paired with a NaN b yields a (no NaN propagation), but a NaN a always propagates.

Opcode	Sub	What it does
`f32x4.ceil`	`0x67`	Round each lane toward +Inf.
`f32x4.floor`	`0x68`	Round each lane toward -Inf.
`f32x4.trunc`	`0x69`	Round each lane toward zero (preserves signed zero).
`f32x4.nearest`	`0x6A`	Round half to even per lane.
`f64x2.ceil` / `floor`	`0x74` / `0x75`	Same shape as `f32x4`, double precision.
`f64x2.trunc`	`0x7A`
`f64x2.nearest`	`0x94`
`f32x4.abs` / `neg`	`0xE0` / `0xE1`	Bit-twiddle the sign bit; NaN payloads preserved.
`f32x4.sqrt`	`0xE3`	`sqrt(-x>0) = NaN`; `sqrt(-0) = -0`.
`f32x4.add` / `sub` / `mul` / `div`	`0xE4` / `0xE5` / `0xE6` / `0xE7`	IEEE-754 per lane. `0/0 = NaN`, `1/0 = +Inf`.
`f32x4.min` / `max`	`0xE8` / `0xE9`	NaN → NaN; `min(-0,+0) = -0`.
`f32x4.pmin` / `pmax`	`0xEA` / `0xEB`	`if b<a then b else a` / `if a<b then b else a`; NaN-compare picks `a`.
`f64x2.abs` / `neg`	`0xEC` / `0xED`	Bit-level sign manipulation.
`f64x2.sqrt`	`0xEF`
`f64x2.add` / `sub` / `mul` / `div`	`0xF0` / `0xF1` / `0xF2` / `0xF3`
`f64x2.min` / `max`	`0xF4` / `0xF5`
`f64x2.pmin` / `pmax`	`0xF6` / `0xF7`

Bitwise + reductions

Six bitwise ops that ignore lane shape (the v128 is just 16 raw bytes), plus nine v128 → i32 reductions. v128.bitselect is the only SIMD ternary op — it takes three v128 operands (a, b, c) and returns (a AND c) OR (b AND NOT c), where c is the selector mask. All 15 ops have no immediate past the sub-opcode.

any_true is shape-agnostic — any byte non-zero returns 1, otherwise 0. *.all_true is lane-shape-aware: a v128 whose bytes are [0, 1, 0, 1, 0, 1, ...] is i8x16.all_true = 0 (every other byte is zero) but i16x8.all_true = 1 (every 16-bit lane is non-zero). *.bitmask packs the MSB of each lane into the i32 result at the lane-indexed bit position (lane 0 → bit 0).

Opcode	Sub	What it does
`v128.not`	`0x4D`	Bitwise complement of all 16 bytes.
`v128.and`	`0x4E`	Bitwise AND.
`v128.andnot`	`0x4F`	`a AND (NOT b)` — note the asymmetry.
`v128.or`	`0x50`	Bitwise OR.
`v128.xor`	`0x51`	Bitwise XOR.
`v128.bitselect`	`0x52`	`(a AND c) OR (b AND NOT c)`; ternary.
`v128.any_true`	`0x53`	`1` if any bit is set, else `0`.
`i8x16.all_true`	`0x63`	`1` iff every byte is non-zero.
`i16x8.all_true`	`0x83`	`1` iff every 16-bit lane is non-zero.
`i32x4.all_true`	`0xA3`	`1` iff every i32 lane is non-zero.
`i64x2.all_true`	`0xC3`	`1` iff both i64 lanes are non-zero.
`i8x16.bitmask`	`0x64`	Top bit of each byte → 16-bit mask in i32.
`i16x8.bitmask`	`0x84`	Top bit of each i16 lane → 8-bit mask.
`i32x4.bitmask`	`0xA4`	Top bit of each i32 lane → 4-bit mask.
`i64x2.bitmask`	`0xC4`	Top bit of each i64 lane → 2-bit mask.

Comparisons

Lane-wise compare ops produce a result lane that is all-1s on true (0xFF… — the bitmask shape v128.bitselect consumes natively) and all-0s on false, in the same lane width as the inputs. Every op is v128 × v128 → v128, no immediate past the sub-opcode. 48 ops in total — three full integer shapes (i8x16 / i16x8 / i32x4) get the full eq, ne, lt_s, lt_u, gt_s, gt_u, le_s, le_u, ge_s, ge_u set; i64x2 gets the six signed forms only (the spec defines no _u variants for i64); f32x4 and f64x2 each get eq, ne, lt, gt, le, ge (no signedness — floats are inherently signed).

IEEE-754 NaN: every f32/f64 compare returns false when either operand is NaN, except ne which returns true. IEEE-754 signed zero: -0.0 == +0.0 is true and -0.0 < +0.0 is false.

Opcode	Sub	Notes
`i8x16.eq` / `ne`	`0x23` / `0x24`	Bit-pattern equality — sign-form doesn’t matter.
`i8x16.lt_s` / `lt_u`	`0x25` / `0x26`	`-1 < 0` is true signed, false unsigned (`0xFF > 0`).
`i8x16.gt_s` / `gt_u`	`0x27` / `0x28`
`i8x16.le_s` / `le_u`	`0x29` / `0x2A`
`i8x16.ge_s` / `ge_u`	`0x2B` / `0x2C`
`i16x8.eq` / `ne`	`0x2D` / `0x2E`
`i16x8.lt_s` / `lt_u`	`0x2F` / `0x30`	Sign-form chooses between two reads of the 16-bit lane.
`i16x8.gt_s` / `gt_u`	`0x31` / `0x32`
`i16x8.le_s` / `le_u`	`0x33` / `0x34`
`i16x8.ge_s` / `ge_u`	`0x35` / `0x36`
`i32x4.eq` / `ne`	`0x37` / `0x38`
`i32x4.lt_s` / `lt_u`	`0x39` / `0x3A`	`_u` uses `Integer.compareUnsigned` per lane.
`i32x4.gt_s` / `gt_u`	`0x3B` / `0x3C`
`i32x4.le_s` / `le_u`	`0x3D` / `0x3E`
`i32x4.ge_s` / `ge_u`	`0x3F` / `0x40`
`i64x2.eq` / `ne`	`0xD6` / `0xD7`
`i64x2.lt_s` / `gt_s`	`0xD8` / `0xD9`	i64x2 has signed-only compares per spec.
`i64x2.le_s` / `ge_s`	`0xDA` / `0xDB`
`f32x4.eq` / `ne`	`0x41` / `0x42`	NaN-involving: every op false except `ne`.
`f32x4.lt` / `gt`	`0x43` / `0x44`
`f32x4.le` / `ge`	`0x45` / `0x46`
`f64x2.eq` / `ne`	`0x47` / `0x48`
`f64x2.lt` / `gt`	`0x49` / `0x4A`
`f64x2.le` / `ge`	`0x4B` / `0x4C`

Narrow / extend / extadd_pairwise / extmul + float-int conv + demote / promote

42 ops covering everything that changes lane width or moves between integer and float lanes. Mechanically: narrow takes two source v128s and packs them into one with saturating clamps; extend (the spec’s name for “widen”) pulls half the source lanes and sign- or zero-extends each into the wider lane width; extadd_pairwise pairs adjacent narrower lanes and sums each pair (with extension) into one wider lane; extmul fuses extend + multiply at the wider lane width so the product fits exactly. The 8 float↔int conversions follow the scalar trunc_sat_* / convert_* rules per lane (NaN → 0, ±overflow saturates). The _zero suffix on the f64x2 / i32x4 form means “result has 4 lanes but only the first 2 carry data, the rest are 0”; _low on the inverse direction means “read only lanes 0..1 of the source”.

Opcode	Sub	What it does
`i8x16.narrow_i16x8_s` / `_u`	`0x65` / `0x66`	Pack 16 Short lanes into 16 saturated Byte lanes (signed `[-128,127]` / unsigned `[0,255]`).
`i16x8.narrow_i32x4_s` / `_u`	`0x85` / `0x86`	Pack 8 Int lanes into 8 saturated Short lanes.
`i16x8.extend_low/high_i8x16_s` / `_u`	`0x87`–`0x8A`	Read 8 bytes (low or high half), sign- or zero-extend each to i16.
`i32x4.extend_low/high_i16x8_s` / `_u`	`0xA7`–`0xAA`	Read 4 i16 lanes (half), extend to i32.
`i64x2.extend_low/high_i32x4_s` / `_u`	`0xC7`–`0xCA`	Read 2 i32 lanes (half), extend to i64.
`i16x8.extadd_pairwise_i8x16_s` / `_u`	`0x7C` / `0x7D`	Pair adjacent bytes, sum with extension into 8 i16 lanes.
`i32x4.extadd_pairwise_i16x8_s` / `_u`	`0x7E` / `0x7F`	Pair adjacent i16 lanes, sum with extension into 4 i32 lanes.
`i16x8.extmul_low/high_i8x16_s` / `_u`	`0x9C`–`0x9F`	Multiply extended low/high bytes at i16 precision (full product).
`i32x4.extmul_low/high_i16x8_s` / `_u`	`0xBC`–`0xBF`	Multiply extended i16 lanes at i32 precision.
`i64x2.extmul_low/high_i32x4_s` / `_u`	`0xDC`–`0xDF`	Multiply extended i32 lanes at i64 precision.
`f32x4.demote_f64x2_zero`	`0x5E`	Round 2 f64 lanes to f32 lanes 0..1; lanes 2 + 3 zero-filled.
`f64x2.promote_low_f32x4`	`0x5F`	Widen f32 lanes 0..1 to f64.
`i32x4.trunc_sat_f32x4_s` / `_u`	`0xF8` / `0xF9`	Per-lane scalar `trunc_sat`: NaN → 0, ±overflow → INT_MIN/MAX (`_s`) or 0/0xFFFFFFFF (`_u`).
`f32x4.convert_i32x4_s` / `_u`	`0xFA` / `0xFB`	Per-lane int → f32; `_u` treats the signed lane as UInt32 first.
`i32x4.trunc_sat_f64x2_s_zero` / `_u_zero`	`0xFC` / `0xFD`	2 f64 → i32 lanes 0..1; lanes 2 + 3 zero-filled.
`f64x2.convert_low_i32x4_s` / `_u`	`0xFE` / `0xFF`	Read i32 lanes 0..1 of source, widen to f64.

Dot product + load_lane / store_lane

Nine ops: one pairwise multiply-add at i32 precision, and eight partial memory accesses that touch a single lane.

i32x4.dot_i16x8_s (the only “wider lane multiply-add” op in the spec) reads two i16x8 vectors, pairs up adjacent lanes (a[2k] * b[2k] + a[2k+1] * b[2k+1]), and produces an i32x4. The i16 lanes are sign-extended to i32 before multiplying, so each product fits exact in i32; the pair-sum can overflow only at -32768² + -32768² = 2³¹, which wraps to Int.MinValue per the spec’s two’s-complement rule. No immediate past the sub-opcode.

v128.load*_lane / v128.store*_lane are the only SIMD ops that carry BOTH a memarg AND a 1-byte lane immediate (after the sub-opcode: memarg LEBs, then a single byte for the lane index). Each load_lane reads N bytes from memory and places them at the named lane of the v128 operand (preserving every other lane); each store_lane writes N bytes from the named lane to memory. Operand stack: [i32 addr, v128 src] → [v128] for load, [i32 addr, v128 src] → [] for store. Lane index is validated < 16/8/4/2 depending on access width. Out-of-bounds (addr + offset + width > mem.size) traps with MemoryOutOfBounds.

Opcode	Sub	What it does
`i32x4.dot_i16x8_s`	`0xBA`	Pairwise multiply-then-add: lane k = `a[2k]b[2k] + a[2k+1]b[2k+1]` with i16 sign-extension to i32. Pair-sum wraps two’s-complement on overflow.
`v128.load8_lane`	`0x54`	Read 1 byte at addr, write into lane (lane idx < 16). Other lanes preserved.
`v128.load16_lane`	`0x55`	Read 2 LE bytes, write into i16 lane (< 8).
`v128.load32_lane`	`0x56`	Read 4 LE bytes, write into i32 lane (< 4).
`v128.load64_lane`	`0x57`	Read 8 LE bytes, write into i64 lane (< 2).
`v128.store8_lane`	`0x58`	Write 1 byte of lane (idx < 16) to memory.
`v128.store16_lane`	`0x59`	Write 2 LE bytes of lane (< 8) to memory.
`v128.store32_lane`	`0x5A`	Write 4 LE bytes of lane (< 4) to memory.
`v128.store64_lane`	`0x5B`	Write 8 LE bytes of lane (< 2) to memory.

Relaxed SIMD

The relaxed-SIMD proposal adds 20 sub-opcodes (0x100..0x113) under the existing 0xFD SIMD prefix. The “relaxed” name reflects that the spec lets each op pick between two or more valid implementations per edge case (NaN handling, out-of-range conversion, sign-extension of partly-used operands); this interpreter pins one deterministic choice each, documented in simd_dispatch.scala and the SimdRelaxedTests fixtures.

Sub-opcode	Op	Shape	Pinned semantics
`0x100`	`i8x16.relaxed_swizzle`	`v128, v128 → v128`	Identical to non-relaxed `i8x16.swizzle`.
`0x101..0x104`	`i32x4.relaxed_trunc_*`	`v128 → v128`	Identical to `i32x4.trunc_sat_*` (NaN → 0, overflow saturates).
`0x105..0x108`	`fx.relaxed_(n)madd`	`v128, v128, v128 → v128`	Unfused: `(±a*b) + c` per lane. Portable across JVM / Scala.js / Native.
`0x109..0x10C`	`*.relaxed_laneselect`	`v128, v128, v128 → v128`	Per lane: high bit of `mask`‘s lane picks `a` (set) or `b` (clear).
`0x10D..0x110`	`fx.relaxed_min` / `_max`	`v128, v128 → v128`	`java.lang.Math.min` / `max` per lane — NaN propagates either way.
`0x111`	`i16x8.relaxed_q15mulr_s`	`v128, v128 → v128`	Saturating signed Q15 multiply: `sat_i16((a*b + 0x4000) >> 15)`.
`0x112`	`i16x8.relaxed_dot_i8x16_i7x16_s`	`v128, v128 → v128`	Pair-sum of (signed-`a` × unsigned-`b`) byte products per i16 lane.
`0x113`	`i32x4.relaxed_dot_i8x16_i7x16_add_s`	`v128, v128, v128 → v128`	4-byte (signed × unsigned) sums per i32 lane plus an i32 accumulator.

Threads + atomics

The threads proposal adds the 0xFE opcode prefix for atomic memory operations and a shared flag on memory limits. This interpreter is single-threaded, but the structural guarantees the proposal makes — alignment-checked load/store, single-step read-modify-write, compare-and-swap — all hold by construction. What’s covered:

Sub-opcode	Op	Shape	Notes
`0x00`	`memory.atomic.notify`	`i32 addr, i32 count → i32`	Always returns 0 (no peer threads).
`0x01`	`memory.atomic.wait32`	`i32 addr, i32 expected, i64 timeout → i32`	Trap if memory unshared; trap “would-block” if value matches expected; else return 1 (not-equal).
`0x02`	`memory.atomic.wait64`	`i32 addr, i64 expected, i64 timeout → i32`	Same as wait32 at 64-bit.
`0x03`	`atomic.fence`	`→`	No-op (single-threaded host).
`0x10..0x16`	`i32/i64.atomic.load[8_u/16_u/32_u]`	`i32 → i32` or `i32 → i64`	Plain load + alignment check.
`0x17..0x1D`	`i32/i64.atomic.store[8/16/32]`	`… →`	Plain store + alignment check.
`0x1E..0x47`	`i32/i64.atomic.rmw{,8,16,32}.{add,sub,and,or,xor,xchg}[_u]`	`i32 addr, T v → T old`	Returns OLD value, leaves `op(old, v)` in memory.
`0x48..0x4E`	`i32/i64.atomic.rmw{,8,16,32}.cmpxchg[_u]`	`i32 addr, T expected, T replacement → T old`	Writes replacement iff old == expected.

Limits-flag encoding:

flag & 0x01 — has-max (unchanged).
flag & 0x02 — shared memory. Validator enforces shared ⇒ has-max. Other bits are rejected with a clear diagnostic.

Validator rules unique to atomics:

The memarg’s align immediate must equal log2(accessWidth). Unlike regular load/store (where alignment is advisory), atomic ops require strict natural alignment — and the validator surfaces a mismatch as InvalidModule at instantiation, not at run time.
Unknown 0xFE sub-opcodes surface as UnknownOpcode(0xFE).

Runtime traps unique to atomics:

UnalignedAtomicAccess — the effective address (base + offset) was not naturally aligned to the access width.
ExpectedSharedMemory — memory.atomic.wait{32,64} ran against a non-shared memory.

The “would-block” case for wait* (the operand value matches expected, so a real implementation would suspend the thread) traps with InvalidModule("…would block forever on a single-threaded host") rather than spinning. The not-equal early-return path is the only observable non-trap result on this interpreter.

Multi-memory

Modules may declare any number of linear memories. Each memory opcode threads a memidx through its immediate:

Load/store memarg — the multi-memory encoding repurposes bit 6 of the alignment LEB as a “memidx-present” flag. When set, a memidx LEB follows; alignment is the LEB with that bit cleared. Single-memory modules emit the original shape (no flag, memidx = 0 implicit).
memory.size / memory.grow / memory.fill — the byte that was a must-be-zero reserved slot becomes a memidx LEB.
memory.copy — two memidx LEBs (dst, src), allowing memory-to-memory copies between distinct memories.
memory.init — second immediate is a memidx LEB (was reserved).

ModuleInstance.memories: Array[Memory] exposes the full vector; .memory keeps backwards compat returning memory 0. .exportedMemory(name) resolves an exported memory by name.

What isn’t implemented yet

Group	Sub-opcodes	Status
GC proposal	`struct.`, `array.`, `ref.cast`, etc.	not planned
Component model	the packaging proposal	out of scope

Each missing group is independently scoped — adding any one of them is a self-contained piece of work that doesn’t touch the others. See the project roadmap on GitHub for the active Phase-8 plan.

Validation pass

Every imported module runs through a separate validator before any code executes. See Concepts → Validation.

Binary sections

Section	ID	What it carries
Type	1	Function signatures
Import	2	Functions, memories, globals, tables imported from the host
Function	3	Function-index → type-index mapping
Table	4	Funcref + externref tables
Memory	5	Linear-memory definitions
Global	6	Module-level globals (scalar + reftype)
Export	7	Names exposed to the host
Start	8	Function index run at instantiate time
Element	9	Table initializers (funcidx + elemexpr forms, funcref + externref)
Code	10	Function bodies
Data	11	Linear-memory initializers (active + passive)
DataCount	12	u32 = number of data segments; required when a function uses `memory.init` or `data.drop`
Tag	13	Exception tag declarations (attribute byte + typeidx)

Custom sections are skipped harmlessly.

ModuleInstance

2026-05-17T00:33:47.893097391Z

Runtime.instantiate(bytes, hostModules) returns Either[WasmError, ModuleInstance]. The Right side is a ModuleInstance — a single, fully-resolved module: imports bound to host functions, data + element segments copied into their target memories / tables, the start function (if any) already invoked. Everything you can do with the module after that goes through this one object.

This page covers the full public surface — what you can read, what you can call, and how host code talks to wasm memory.

The surface

final class ModuleInstance:
  /** All linear memories the module declared, indexed by memidx.
    * Always at least length 1 (zero-memory modules get a synthetic placeholder
    * at index 0). Multi-memory modules carry one entry per declared memory. */
  val memories: Array[Memory]

  /** Convenience accessor for `memories(0)`. Most modules have exactly one
    * memory; this stays the friendly name. */
  val memory: Memory

  /** Invoke an exported function. Returns `Right(results)` on a normal
    * return, `Left(WasmError)` on any trap or signature mismatch. */
  def invoke(name: String, args: Seq[Value] = Seq.empty): Either[WasmError, Seq[Value]]

  /** Total number of functions the module owns (imported + defined). */
  def functionCount: Int

  /** Sorted list of every exported function name. */
  def exportedFunctionNames: Seq[String]

  /** Read an exported global by name. Returns the current value
    * (mutable globals reflect prior `global.set` writes). */
  def globalValue(name: String): Either[WasmError, Value]

  /** Resolve an exported memory by name. For single-memory modules
    * that export memory 0, this is equivalent to `Right(memory)`. */
  def exportedMemory(name: String): Either[WasmError, Memory]

  /** Resolve an exported table by name. */
  def exportedTable(name: String): Either[WasmError, RuntimeTable]

  /** Live cell backing an exported global. Sharing this cell with
    * another module's import preserves the wasm-spec rule that
    * imported mutable globals alias the exporter's storage. */
  def exportedGlobalCell(name: String): Either[WasmError, GlobalCell]

  /** Mutability flag of an exported global — needed by hosts
    * forwarding one module's globals as another module's imports
    * (the wasm mutability-matching rule rejects the import if the
    * advertised flavour is wrong). */
  def exportedGlobalMutability(name: String): Either[WasmError, Boolean]

  /** Declared signature of an exported function. Needed when
    * re-exporting a function as another module's host import — the
    * importer needs the callee's actual `FuncType` to type-check the
    * call site. */
  def exportedFunctionType(name: String): Either[WasmError, FuncType]

  /** Enumerated export-name lists, sorted. Sibling to
    * `exportedFunctionNames`; used by hosts that want to walk every
    * exposed binding. */
  def exportedMemoryNames: Seq[String]
  def exportedTableNames:  Seq[String]
  def exportedGlobalNames: Seq[String]

Everything else on the class is private[wasm] and exists for the interpreter’s eval loop.

Invoking exports

invoke is the workhorse. Arguments are wrapped Values (I32, I64, F32, F64, V128, RefFunc, RefExtern, RefNull); results come back as a Seq[Value] in the function’s declared order:

inst.invoke("add", Seq(I32(2), I32(3))) match
  case Right(Seq(I32(sum)))     => println(s"add = $sum")
  case Right(other)             => println(s"unexpected shape: $other")
  case Left(WasmError.ExportNotFound(n)) => println(s"no export named '$n'")
  case Left(err)                => println(s"trap or signature mismatch: $err")

Failure modes:

ExportNotFound(name) — the export doesn’t exist (or names a non-function export).
TypeMismatch — the args don’t match the function’s declared signature.
Any other WasmError — a runtime trap inside the function (out-of-bounds memory, division by zero, indirect call type mismatch, etc.). See Traps and errors.

exportedFunctionNames gives you the full export list, sorted, when you don’t know what’s available up front:

inst.exportedFunctionNames.foreach(println)

This is what wasm --list-exports uses internally.

Reading globals

Mutable globals are live state — invoke calls can modify them, and globalValue reads them at whatever value they happen to hold right now:

inst.globalValue("counter") match
  case Right(I32(n)) => println(s"counter = $n")
  case Right(other)  => println(s"unexpected type: $other")
  case Left(err)     => println(s"no such global: $err")

inst.invoke("bump")               // module mutates `counter`
inst.globalValue("counter")       // new value visible here

Only globals listed in the module’s export section are reachable through globalValue. Module-internal globals stay private.

Reading + writing memory

memory exposes the underlying Memory for memory 0. Multi-memory modules can reach the rest via memories(idx) or exportedMemory(name):

final class Memory:
  /** The full byte buffer. Mutable — host code may read or write directly.
    * Resized in place when wasm code runs `memory.grow`. */
  var data: Array[Byte]

  /** Bytes currently allocated (= currentPages * 65536). */
  def size: Int

  /** Current and maximum page counts. A page is 64 KiB. */
  var currentPages: Int
  val maxPages: Option[Int]

  /** Grow by `delta` 64-KiB pages. Returns the previous page count on
    * success, or -1 if the grow would exceed `maxPages` or the platform
    * cap. `delta == 0` is a permitted no-op. */
  def grow(delta: Int): Int

Memory is byte-addressable and little-endian, matching the WebAssembly spec. Host code can read or write data directly — the interpreter holds no separate “live view” of memory; what you see is what wasm sees:

// Plant a UTF-8 string at offset 0
val msg = "Hello, host!\n".getBytes("UTF-8")
System.arraycopy(msg, 0, inst.memory.data, 0, msg.length)

// Now wasm can read from address 0 with i32.load8_u + a length argument
inst.invoke("print_at", Seq(I32(0), I32(msg.length)))

Conversely, after a module writes through memory.store, the host reads the same bytes:

inst.invoke("compute_into", Seq(I32(64)))     // writes 16 bytes at offset 64
val out = java.util.Arrays.copyOfRange(inst.memory.data, 64, 80)

memories (the full vector) and exportedMemory(name) matter only for multi-memory modules — single-memory programs can stay on .memory forever.

Concurrency

A ModuleInstance is not thread-safe. invoke mutates the interpreter’s per-instance value stack, frame stack, and memory; running two invoke calls against the same instance from two threads will corrupt that state. If you need concurrency, instantiate the same bytes multiple times — instantiation is cheap and produces independent state.

The bytes array passed to Runtime.instantiate is read-only after parsing; sharing it across multiple instantiate calls is safe and is the recommended pattern for “fork an isolated copy of this module per request”.

Lifecycle

There is no explicit close or dispose on ModuleInstance. Drop the reference and the GC reclaims it — the underlying Memory.data arrays are plain Array[Byte], no off-heap allocation. Host functions registered through HostModule are also pure Scala values; they’re collected when no instance references them.

Where to go next

Host imports — wire your own functions into a module.
Traps and errors — the WasmError model that surfaces through invoke.
Reference → Errors — every error variant in one table.

Installation

2026-05-17T00:33:47.893097391Z

Maven Central

Released artifacts (Scala 3, cross-built on JVM / Scala.js / Scala Native):

libraryDependencies ++= Seq(
  "io.github.edadma" %%% "wasm"      % "0.4.0",
  "io.github.edadma" %%% "wasm-wasi" % "0.4.0",  // optional — only if you want the WASI shim
)

%%% (triple %) is the sbt-crossproject form that picks the right artifact for each platform — drop one % if you’re on a non-cross build. The CLI (wasm-cli) is built from this repo but is not published; it’s a runnable example, not a library.

Coordinate	What you get
`io.github.edadma:wasm:0.4.0`	The interpreter — `Runtime.instantiate`, `ModuleInstance`.
`io.github.edadma:wasm-wasi:0.4.0`	The WASI Preview 1 host shim — depends on `wasm`.

The wasm artifact has zero external runtime dependencies; the wasm-wasi artifact depends only on wasm.

From source

If you want to build the repo locally — to run the test suite, hack on the interpreter, or use the CLI runner — clone and run:

git clone https://github.com/edadma/wasm.git
cd wasm
sbt test                                              # whole tree, all backends# whole tree, all backends
sbt 'interpJVM/Test/run'                              # 653 interpreter tests, JVM
sbt 'wasiJVM/Test/run'                                # 209 WASI tests, JVM
sbt 'cliJVM/Test/run'                                 # 19 CLI tests

The aggregate sbt test runs the interpreter and WASI suites on JVM, Scala.js (Node 20+), and Scala Native, plus the CLI suite on the JVM. 881 tests total on JVM; the interpreter and WASI also pass on JS and Native.

Linking against a local checkout

If you’re hacking on the interpreter and want a downstream project to pick up your changes without a publishSigned round-trip, point the downstream sbt build at the local source tree:

lazy val wasm = ProjectRef(file("../wasm"), "interpJVM")
lazy val wasi = ProjectRef(file("../wasm"), "wasiJVM")

lazy val myProject = project
  .dependsOn(wasm, wasi)

The same trick works for cliJVM, interpJS, interpNative, etc.

Cross-build matrix

Target	Version	Runtime requirement
Scala	3.8.3	—
JVM	—	Java 17 or newer
Scala.js	1.21.0	Node.js 20+
Scala Native	0.5.11	Clang

Verifying the install

Drop this in any @main source file inside the cloned repo, run with sbt 'interpJVM/run', and you should see 120:

import io.github.edadma.wasm.*

@main def smoke(): Unit =
  // The committed `fact.wasm` fixture is a factorial export — fact(5) = 120.
  val bytes = java.nio.file.Files.readAllBytes(
    java.nio.file.Paths.get("interp/shared/src/test/resources/fixtures/fact.wasm")
  )
  Runtime.instantiate(bytes, Seq(EnvModule.default)) match
    case Right(inst) =>
      inst.invoke("fact", Seq(I32(5))) match
        case Right(Seq(I32(v))) => println(v)
        case Right(_)           => println("no result")
        case Left(err)          => println(s"trap: $err")
    case Left(err) => println(s"instantiate failed: $err")

If you see 120, you’re done. Move on to the Quickstart for a tour of the API surface most callers actually use.

Host imports

2026-05-17T00:33:47.893097391Z

WebAssembly modules can declare imports of four kinds: functions, globals, memories, and tables. The interp library exposes all four through the HostModule trait — guest declarations like (import "env" "foo" (func ...)), (import "env" "bar" (global ...)), (import "env" "mem" (memory ...)), and (import "env" "tab" (table ...)) all resolve against the host modules you hand to Runtime.instantiate.

trait HostModule:
  def name: String
  def functions:      Map[String, HostFunc]        = Map.empty
  def functionsMulti: Map[String, HostFuncMulti]   = Map.empty
  def globals:        Map[String, HostGlobal]      = Map.empty
  def memories:       Map[String, Memory]          = Map.empty
  def tables:         Map[String, RuntimeTable]    = Map.empty

type HostFunc      = (Memory,             Seq[Value]) => Seq[Value]
type HostFuncMulti = (IndexedSeq[Memory], Seq[Value]) => Seq[Value]

// HostGlobal is internally backed by a GlobalCell. Two factories:
//   - HostGlobal(vt, mut, value)        — wraps the value in a fresh cell
//   - HostGlobal.live(vt, mut, cell)    — shares an externally-owned cell

final class GlobalCell(var value: Value)

A HostFunc takes the guest’s Memory instance (memidx 0) plus a sequence of Value arguments matching the import’s declared signature, and returns a sequence of Value results matching the import’s declared results. Pure functions, no Future / IO wrapping.

A HostFuncMulti takes the guest’s full vector of memories (length ≥ 1) instead of just memidx 0 — useful only for multi-memory modules. Single-memory programs should stay on HostFunc; multi-memory hosts that need to inspect or write a non-zero memidx use HostFuncMulti. A name registered in both maps resolves to the multi-memory form.

A HostGlobal is a typed global the host exposes for guest modules to import as (import "..." "..." (global <type>)). The declared valueType and mutable flag must match the import declaration exactly. Internally, every HostGlobal is backed by a GlobalCell — a tiny mutable holder for one Value:

HostGlobal(vt, mut, value) wraps the literal in a fresh cell that nobody else holds a reference to. Guest global.set updates this private cell. Use this for immutable globals (where there’s nothing to share anyway) and for mutable globals the host doesn’t need to read back.
HostGlobal.live(vt, mut, cell) shares an externally-owned cell. The host keeps a reference; guest writes flow through the same storage; the host can read and write the cell directly. This is how to satisfy the wasm-3.0 spec’s “imported mutable globals alias the exporter’s storage” rule when forwarding one module’s exports as another module’s imports.

A Memory or RuntimeTable exposed via memories / tables forwards by reference — guest reads and writes hit the same backing array the host can inspect. Limits checking happens at instantiation: the host’s current size must be at least the importing module’s declared min, and the host’s max (if any) must be at most the module’s declared max (if any). Reftype must match for tables; shared-vs-unshared must match for memories.

EnvModule.default

The interpreter ships one host module out of the box:

import io.github.edadma.wasm.*

EnvModule.default     // module name: "env", one function: "putchar"

env.putchar(i32) → () writes the low byte of its argument to System.out. It’s the minimal “I can print” surface — modules compiled by lightweight toolchains use it when no WASI runtime is available.

To redirect the output (tests, in-process capture, custom encoding):

val buf = new java.lang.StringBuilder
EnvModule.withWriter(c => buf.append(c.toChar))   // returns a HostModule

Defining your own HostModule

import io.github.edadma.wasm.*

object Logger extends HostModule:
  def name: String = "logger"

  def functions: Map[String, HostFunc] = Map(
    "log_i32" -> { (_: Memory, args: Seq[Value]) =>
      val I32(level) +: I32(code) +: _ = args: @unchecked
      println(s"log level=$level code=$code")
      Seq.empty
    },

    "log_str" -> { (mem: Memory, args: Seq[Value]) =>
      // Convention: caller pushes (ptr: i32, len: i32) onto the stack.
      val I32(ptr) +: I32(len) +: _ = args: @unchecked
      val bytes = new Array[Byte](len)
      System.arraycopy(mem.data, ptr, bytes, 0, len)
      println(new String(bytes, "UTF-8"))
      Seq.empty
    },
  )

// Pass it alongside whatever else the module needs:
Runtime.instantiate(bytes, Seq(EnvModule.default, Logger)) match
  case Right(inst) => inst.invoke("main", Seq.empty)
  case Left(err)   => println(err)

The guest module’s import section declares the imports by (module, name) pair:

(module
  (import "logger" "log_str" (func $log (param i32 i32)))
  ...
  (call $log (i32.const 100) (i32.const 13)))

The interpreter looks up "logger" in the supplied list of host modules, then "log_str" in that module’s functions map. Missing module: Left(UnknownImport("logger", "log_str")) at instantiate time. Missing function in a found module: same error.

Memory access from host code

Memory.data is a public Array[Byte] — host functions read and write the guest’s linear memory directly through it. Bounds-checking is the host function’s responsibility (the array’s own IndexOutOfBoundsException is what fires on an out-of-range access, and the interpreter doesn’t catch that on the host side). Use mem.size to find the current byte length; use mem.currentPages and mem.maxPages for the page-count view.

For multi-byte loads, wasm is little-endian:

def readI32(mem: Memory, addr: Int): Int =
  (mem.data(addr)     & 0xff)        |
  (mem.data(addr + 1) & 0xff) <<  8  |
  (mem.data(addr + 2) & 0xff) << 16  |
  (mem.data(addr + 3) & 0xff) << 24

def writeI32(mem: Memory, addr: Int, v: Int): Unit =
  mem.data(addr)     = (v        & 0xff).toByte
  mem.data(addr + 1) = ((v >>  8) & 0xff).toByte
  mem.data(addr + 2) = ((v >> 16) & 0xff).toByte
  mem.data(addr + 3) = ((v >> 24) & 0xff).toByte

The WASI shim wraps these patterns; if you find yourself writing them repeatedly, see wasi/Wasi.scala for production-quality versions.

Why not a typed binding generator?

The host-import surface is deliberately a Map[String, HostFunc] of dynamically-typed functions rather than a typed binding generated from .wit or .wasm. Two reasons:

Zero external dependencies. No code-gen step at compile time means no Scala-version constraint and no annotation-processor wiring. Drop the jar on the classpath and go.
Multi-platform shared code. The same HostModule definition compiles for JVM, Scala.js, and Scala Native without @JSExport / @ExportTopLevel annotations — the Value types are platform-agnostic.

For a stronger-typed wrapper, a separate wasm-bindgen-style library could be layered on top without touching the interp core.

Multi-memory host functions

When a guest module declares more than one linear memory (a multi-memory proposal feature; see Opcodes → Multi-memory), HostFunc only gets a handle to memidx 0. Register through functionsMulti instead to receive the whole IndexedSeq[Memory]:

import io.github.edadma.wasm.*

object DualBuffer extends HostModule:
  def name: String = "dual"

  override def functionsMulti: Map[String, HostFuncMulti] = Map(
    // Copies one byte from mem0 into mem1 at the same offset.
    "mirror" -> { (mems: IndexedSeq[Memory], args: Seq[Value]) =>
      val I32(addr) +: _ = args: @unchecked
      mems(1).data(addr) = mems(0).data(addr)
      Seq.empty
    },
  )

The vector is always length ≥ 1 — zero-memory modules get a synthetic placeholder at index 0 so mems.head is safe to dereference. Single-memory HostFunc registrations continue to work unchanged against single-memory modules; the runtime wraps them at import-resolution time so they always see mems.head.

Flags

2026-05-17T00:33:47.893097391Z

`<file>` (positional)

Path to the .wasm binary to run. Required. The file is read as raw bytes; nothing about the path matters beyond that — there’s no virtual-fs lookup, no env-var substitution.

`<wasi-args>...` (trailing positional)

Anything positional after <file> is captured and passed to the WASI program’s _start as argv[1..]. argv[0] is synthesised from the file basename (stripped of any .wasm suffix), matching the wasmtime / wasmer convention.

sbt 'cliJVM/run --preopen ./data:/data examples/rust/word_count.wasm /data/input.txt'
# argv inside word_count.wasm: ["word_count", "/data/input.txt"]

If any value starts with - it would otherwise be parsed as a CLI flag — use the standard POSIX -- separator to stop option parsing:

sbt 'cliJVM/run examples/rust/word_count.wasm -- -v --quiet /data/input.txt'
# argv: ["word_count", "-v", "--quiet", "/data/input.txt"]

Non-WASI modules (main or --invoke-named exports) don’t see these args — argv is a WASI concept; non-WASI exports take i32 operands through --args instead.

`-i`, `--invoke <export>`

Name of the export to invoke. Overrides the default dispatch. Use this when the module exports neither _start nor main, or when you want to run a specific function instead of the default entry point:

sbt 'cliJVM/run --invoke fact -a 5 examples/fact.wasm'
# 120

`-a`, `--args n1,n2,...`

Comma-separated decimal i32 values to pass as arguments to the invoked export. Each n is parsed as Int.parseInt(_), so values must fit in a signed 32-bit int. Negative numbers, hex, and floats are not accepted.

--args only applies when the dispatch is not _start (the WASI command-mode entry point takes no wasm-level arguments — its argv comes from the WASI context, populated by trailing positional args after <file>; see <wasi-args>... above). When dispatch is main or an --invoke-named export, the --args values are pushed onto the operand stack in order before the call.

`--list-exports`

Prints every exported function name on its own line and exits with status 0. No instantiation traps run, no _start fires, no preopens are needed.

sbt 'cliJVM/run --list-exports interp/shared/src/test/resources/fixtures/fact.wasm'
# fact
# memory

`-e`, `--env <key>=<value>`

Sets an environment variable for the WASI program. Repeatable; each --env adds one entry to WasiContext.envs in order. Empty keys (=value) are rejected; values may themselves contain = signs (PATH=/usr/bin:/bin is fine).

sbt 'cliJVM/run -e HOME=/root -e LANG=C.UTF-8 my-program.wasm'

From the guest’s perspective, these reach userspace through environ_sizes_get + environ_get. std::env::vars() in Rust, getenv in C through wasi-libc.

--env is for WASI programs specifically — non-WASI modules don’t have an environ surface.

`-p`, `--preopen <host-path>:<virtual-name>`

Mounts a real host directory as a wasi preopen, backed by HostPreopen.fromDir. Repeatable; each --preopen adds one entry to the WASI context’s preopen list in order.

The split is on the last colon in the spec, so Windows-style paths like C:\data:/data parse correctly (C:\data host → /data virtual). The virtual name should start with / — that’s the convention wasi-libc expects, and it’s what guest code matches path_open calls against.

sbt 'cliJVM/run -p /tmp/sandbox:/sandbox -p /var/log:/logs my-program.wasm'

If a --preopen‘s host path doesn’t exist or isn’t a directory, the CLI exits with an error before instantiating the module.

`--stdin <path>`

Redirects the guest’s fd 0 (stdin) to read from a host file. The file is read once at startup and streamed byte-for-byte through fd_read until exhausted (subsequent reads return 0 = EOF).

echo "hello" > /tmp/in.txt
sbt 'cliJVM/run --stdin /tmp/in.txt examples/wc.wasm'

When omitted, fd 0 reads return 0 (EOF) immediately — wasi programs that probe stdin without writing prerequisites still terminate cleanly. A non-existent --stdin path is rejected with a clear diagnostic before instantiation.

Non-WASI modules never call fd_read, so this flag is inert for them.

`--trace`

Installs a counting Tracer on the run and prints the totals to stderr after _start / main / --invoke returns:

$ sbt 'cliJVM/run --trace examples/hello.wasm'
Hello, world!
[trace] ops=53 calls=2 hostCalls=14 throws=0 traps=0 maxDepth=2

Counts are: opcode dispatches (ops), wasm-defined function calls (calls), host-function calls (hostCalls), throw opcodes (throws), traps surfaced as WasmError (traps), and the maximum wasm-frame depth observed at any point.

Use this for quick performance / instrumentation triage. For finer-grained tracing (per-block, per-branch), write your own Tracer implementation and wire it through the library API — the CLI’s --trace deliberately picks the minimal default.

`--validate-only`

Parse and validate the module, then exit. No instantiation, no start function, no host imports needed. Useful as a CI lint step on generated wasm:

$ wasm-cli --validate-only build/output.wasm
build/output.wasm: ok

$ wasm-cli --validate-only build/broken.wasm
build/broken.wasm: InvalidModule(function 0: byte offset 0x12: expected i32, got i64)

Exit code is 0 if the binary parses and the validator accepts every function body; 1 with the diagnostic otherwise. Any other CLI flags (--preopen, --invoke, etc.) are ignored when --validate-only is set.

`--help` / `--version`

Standard. --help prints the synopsis above; --version prints wasm 0.4.0 and exits.

Dispatch rules

The CLI picks what to invoke based on what’s exported:

If --invoke is given, that export is invoked. _start and WASI dispatch are bypassed.
Otherwise, if the module exports _start, it’s treated as a WASI command-mode binary. The CLI runs it through Wasi.run, so proc_exit(N) becomes the process exit code, args/envs/preopens go through WasiContext, trailing positional args become argv[1..], and --args is ignored.
Otherwise, if the module exports main, that’s invoked. --args is passed to it as i32 operands; trailing positional args are ignored.
Otherwise, the CLI exits with ExportNotFound("_start") (the default it tried first).

Exit codes

0 — clean exit (WASI _start returned, or non-WASI export returned a single non-trapping result).
N (1–255) — proc_exit(N) from a WASI binary.
1 — any non-proc_exit failure (parse error, validator error, instantiate error, trap during execution, missing export).

Non-WASI exports that return a single i32 print the result to stdout as result: <decimal>; multi-result exports print result: <decimal>, <decimal>, …. Zero-result exports print nothing.

Errors

2026-05-17T00:33:47.893097391Z

sealed trait WasmError

object WasmError:
  case object InvalidMagic                                          extends WasmError
  case object TypeMismatch                                          extends WasmError
  case object UnreachableExecuted                                   extends WasmError
  case object MemoryOutOfBounds                                     extends WasmError
  final case class UnknownOpcode(byte: Int)                         extends WasmError
  final case class UnknownImport(module: String, name: String)      extends WasmError
  final case class ExportNotFound(name: String)                     extends WasmError
  final case class InvalidModule(message: String)                   extends WasmError
  final case class UncaughtException(tagIdx: Int, args: Seq[Value]) extends WasmError
  case object UnalignedAtomicAccess                                 extends WasmError
  case object ExpectedSharedMemory                                  extends WasmError

Lookup

Variant	Origin	Trigger
`InvalidMagic`	parser	First 4 bytes aren’t `\0asm`.
`TypeMismatch`	runtime	A typed slot received a `Value` of the wrong tag — almost always an interpreter or host-binding bug.
`UnreachableExecuted`	runtime	Guest executed an `unreachable` opcode.
`MemoryOutOfBounds`	runtime	Load/store/`memory.copy`/`memory.fill`/`memory.init` accessed past linear memory’s end.
`UnknownOpcode(b)`	parser	Byte stream contained an opcode this interpreter doesn’t recognise.
`UnknownImport(m, n)`	instantiate	Module imports `m.n`, but no `HostModule` provides it.
`ExportNotFound(name)`	runtime	`inst.invoke(name, …)` or `Wasi.run(inst, name)` looked up a non-existent export.
`InvalidModule(message)`	validator + runtime traps	Static type-check failure, or a runtime trap that isn’t a memory bound — divide-by-zero, signed-`div` overflow, `trunc` of NaN, `call_indirect` signature mismatch, branch index out of range, etc. The message names the operation.
`UncaughtException(tag, args)`	runtime	A `throw` propagated past the outermost call without a matching `catch tagidx` / `catch_all`. `tag` is the unified tagidx (imports first, then defs); `args` is the payload, top-of-stack at throw site = last element.
`UnalignedAtomicAccess`	runtime	Threads proposal: the effective address of an atomic memory op (base + memarg.offset) was not naturally aligned to the access width.
`ExpectedSharedMemory`	runtime	Threads proposal: `memory.atomic.wait{32,64}` was executed against a memory that wasn’t declared `shared` (limits flag bit 0x02).

InvalidModule prefixes

Validator-stage messages always start with the function index and byte offset:

function 7: byte offset 0x1a3: i32.add expected i32 i32 on stack, found i32 f64
function 7: byte offset 0x205: br target depth 3 out of range (max 2)

Runtime-trap messages don’t include byte offsets — they name the trapping operation:

i32.div_s: divide by zero
i32.trunc_f32_s: value out of range
call_indirect: signature mismatch
call_indirect: undefined table element
br_table: index out of range

You can pattern-match on the prefix if you need to distinguish them programmatically — but the standard recovery is case Left(InvalidModule(msg)) => log(msg) without sub-parsing.

Pattern-match template

import io.github.edadma.wasm.WasmError.*

result match
  case Right(value) =>
    handle(value)

  // -- failure to even get to running guest code --
  case Left(InvalidMagic)               => println("not a wasm binary")
  case Left(UnknownOpcode(b))           => println(f"parser: unknown opcode 0x$b%02x")
  case Left(UnknownImport(m, n))        => println(s"missing import: $m.$n")
  case Left(InvalidModule(msg))         => println(s"module rejected: $msg")

  // -- failure during guest execution --
  case Left(UnreachableExecuted)        => println("guest hit unreachable")
  case Left(MemoryOutOfBounds)          => println("guest read/wrote out of bounds")
  case Left(ExportNotFound(name))       => println(s"no such export: $name")
  case Left(UncaughtException(t, args)) => println(s"uncaught wasm exception: tag=$t payload=$args")
  case Left(UnalignedAtomicAccess)      => println("atomic op: misaligned effective address")
  case Left(ExpectedSharedMemory)       => println("atomic wait: target memory is not shared")

  // -- host or interpreter bug --
  case Left(TypeMismatch)                => println("internal type tag mismatch (bug)")

The first group (parse / instantiate failures) surfaces only from Runtime.instantiate. The second group surfaces from inst.invoke(...) or Wasi.run(...). The third group can surface anywhere and indicates something is wrong with the interpreter or host-import wiring, not the guest.

WASI errnos vs. WasmError

WASI syscalls return their own errno space (Wasi.ENOENT = 44, Wasi.EBADF = 8, Wasi.ENOTCAPABLE = 76, …) inside the wasm-level return value of the syscall. Those are not WasmError values — they’re Ints the guest reads. A WASI program that tries to open /notfound gets EBADF-or-ENOENT from the syscall, and the host shim returns Right(...) to the interpreter; the wasm execution continues normally. Left(WasmError) is reserved for cases where the host can’t make further progress at all.

WasiContext

2026-05-17T00:33:47.893097391Z

WasiContext is the configuration record Wasi.preview1(ctx) accepts. It’s a plain case class with nine fields, all of which have sensible defaults:

final case class WasiContext(
    args:     Seq[String]                       = Seq.empty,                   // argv
    envs:     Seq[(String, String)]             = Seq.empty,                   // KEY=VALUE pairs
    stdout:   Int => Unit                       = WasiContext.defaultStdout,   // per-byte sink for fd 1
    stderr:   Int => Unit                       = WasiContext.defaultStderr,   // per-byte sink for fd 2
    stdin:    (Array[Byte], Int, Int) => Int    = WasiContext.defaultStdin,    // reader for fd 0
    clock:    WasiContext.Clock                 = WasiContext.systemClock,     // realtime + monotonic
    random:   Int => Array[Byte]                = WasiContext.defaultRandom,   // random_get source
    preopens: Seq[WasiContext.Preopen]          = Seq.empty,                   // fd 3 .. 3+P-1
    sockets:  Seq[WasiContext.ServerSocket]     = Seq.empty,                   // fd 3+P .. 3+P+S-1
)

The stdin reader has the POSIX read shape: fill dst[off .. off + len) with up to len bytes from the current stream position, return the number of bytes written (0 = EOF, never negative). The default returns 0 immediately, so a program that reads stdin without one being supplied sees a clean empty input rather than EBADF. WasiContext.stdinFromBytes(bytes) builds a cursor-tracking reader from an Array[Byte]; the CLI’s --stdin <path> uses it to stream a file through fd 0.

Every wasi syscall that needs host state reads from this record — args_get walks args, clock_time_get calls clock.realtimeNanos(), random_get calls random(n), and so on. Copy-and-modify (ctx.copy(args = …)) is the only way to construct one; there is no mutation.

Factories

`WasiContext.default`

val ctx = WasiContext.default

Equivalent to WasiContext() — every field at its default. stdout / stderr go to System.out / System.err, the clock walks System.currentTimeMillis + System.nanoTime, random uses scala.util.Random, no args, no envs, no preopens.

Use it when running a real binary outside tests. Pair it with .copy(...) to override individual fields:

val ctx = WasiContext.default.copy(
  args     = Seq("myprog", "input.txt"),
  preopens = Seq(HostPreopen.fromDir("/var/data", "/data")),
)

`WasiContext.collecting(...)`

val collecting = WasiContext.collecting(
  args     = Seq("myprog", "--flag"),
  envs     = Seq("LANG" -> "C"),
)
val ctx = collecting.context

Same shape as WasiContext.default but redirects stdout and stderr into ArrayBuffer[Byte]s you can read back after the guest runs:

collecting.stdoutBytes   // Array[Byte]
collecting.stderrBytes   // Array[Byte]
collecting.stdoutString  // String (UTF-8 decoded)
collecting.stderrString  // String (UTF-8 decoded)

This is what the WASI test suite uses to assert against program output without touching the real stdout/stderr. The clock / random / preopens overrides flow through identically, so the same factory works for any test that wants deterministic clock or random reads as well.

Collecting is single-threaded — the interpreter is single-threaded, and the underlying buffers aren’t synchronized. Don’t share a Collecting across threads.

Constructing from scratch

Both factories produce a WasiContext. If neither fits, build one directly:

val ctx = WasiContext(
  args     = Seq("prog"),
  envs     = Seq("PATH" -> "/usr/bin"),
  stdout   = b => myLogger.write(b),
  stderr   = b => myLogger.write(b),
  clock    = myClock,
  random   = myRandom,
  preopens = Seq(myPreopen),
)

The `Clock` trait

trait Clock:
  def realtimeNanos():  Long       // wall clock, nanoseconds since Unix epoch
  def monotonicNanos(): Long       // arbitrary anchor, nanoseconds; only deltas matter

clock_time_get(id, ...) dispatches against this. Four wasi clockid_t values map onto these two methods:

`clockid_t`	Backing method
`CLOCK_REALTIME`	`realtimeNanos()`
`CLOCK_MONOTONIC`	`monotonicNanos()`
`CLOCK_PROCESS_CPUTIME`	`monotonicNanos()` (folded)
`CLOCK_THREAD_CPUTIME`	`monotonicNanos()` (folded)

WasiContext.systemClock is the default — System.currentTimeMillis() * 1_000_000L for realtime, System.nanoTime() for monotonic. Cross-platform: JVM, Scala.js (via Date.now / performance.now), and Scala Native all support both calls without conditional code.

For deterministic tests, plug in your own:

val frozenClock = new WasiContext.Clock:
  def realtimeNanos():  Long = 1_700_000_000_000_000_000L
  def monotonicNanos(): Long = 42L

val ctx = WasiContext.default.copy(clock = frozenClock)

The `random` closure

random: Int => Array[Byte]

random_get(buf, len) calls ctx.random(len) and copies the result into linear memory at buf. The closure must return an array of exactly len bytes — shorter returns are not detected and would surface as silent zero-fill in the guest. The default implementation (WasiContext.defaultRandom) uses scala.util.Random.nextBytes; not cryptographic, but adequate for getrandom-style entropy in most cases.

Override for deterministic tests:

val ctx = WasiContext.default.copy(
  random = (n: Int) => Array.fill(n)(0x42.toByte),
)

Or for a real CSPRNG, wire java.security.SecureRandom (JVM/Native) or crypto.randomBytes (JS) in here.

stdout / stderr sinks

stdout and stderr are per-byte callbacks. Every fd_write(1, …) byte goes through stdout; every fd_write(2, …) byte goes through stderr. They’re called exactly once per byte the guest writes, in order — they’re not aware of newlines or line buffering.

If you want line-buffered output, do the buffering in your callback:

val lineBuf = new StringBuilder
val stdout: Int => Unit = b =>
  if b == '\n' then
    println(lineBuf.toString)
    lineBuf.clear()
  else
    lineBuf += b.toChar

val ctx = WasiContext.default.copy(stdout = stdout)

The `sockets` field

sockets: Seq[WasiContext.ServerSocket] — host-provided listening sockets, exposed to the guest one fd at a time starting at 3 + preopens.length. There is no sock_open / sock_bind / sock_listen in Preview 1; the host pre-binds and the guest can only sock_accept against the inherited fds.

JVM and Scala Native get a factory:

val (listener, port) = HostServerSocket.bind(0)   // 0 → OS-chosen ephemeral
val ctx = WasiContext.default.copy(sockets = Seq(listener))

Scala.js doesn’t link java.net.ServerSocket; a Node-backed program that needs sockets must supply its own WasiContext.ServerSocket implementation (typically wrapping Node’s net module).

The trait surface is intentionally tiny:

trait ServerSocket:
  def accept(): Either[Int, ClientSocket]
  def address: String        // "host:port" for debug logs

trait ClientSocket extends Wasi.FsFile:
  def shutdown(how: Int): Either[Int, Unit]
  // close/read/write inherited from FsFile — fd_read/fd_write
  // route to them through the standard FdTable lookup.

accept blocks until a client connects; the returned ClientSocket is installed in the per-instance fd table by sock_accept and is observable through both fd_read / fd_write (the generic byte-stream surface) and the dedicated sock_recv / sock_send (the iovec-shape recv/send surface with recvflags/sendflags).

Where to go next

Preopens — the preopens field in depth.
Syscalls — which fields each syscall reads.
Concepts → ModuleInstance — what Wasi.preview1(ctx) returns and how to drive it.

Architecture

2026-05-17T00:33:47.893097391Z

Three sub-projects

The repo splits into three sub-projects so the published libraries stay dependency-free:

Sub-project	Published as	Depends on	External runtime deps
`interp/`	`wasm`	Scala stdlib only	None
`wasi/`	`wasm-wasi`	`interp`	None
`cli/`	(not published)	`interp` + `wasi`	`scopt`

interp/ — the interpreter itself: parser, validator, runtime, interpreter loop, host-import surface. Cross-built on JVM / Scala.js / Scala Native; the same shared/ sources compile for every backend.
wasi/ — the WASI Preview 1 host shim (29 syscalls). Also zero external deps. Pulls interp in transitively.
cli/ — a small command-line runner. Depends on scopt for argument parsing; not published because it’s a runnable example, not a library. JVM / Scala.js (Node) / Scala Native builds are all wired up.

Source-tree layout

build.sbt                              three crossProjects + Fixtures.scala generator
project/
interp/                                cross-platform interpreter library (zero deps)
  shared/src/
    main/scala/io/github/edadma/wasm/  types, parser, validator, interpreter, runtime, host
    test/scala/io/github/edadma/wasm/  category-split tests + zero-dep runner
    test/resources/fixtures/           .wat sources + wat2wasm-produced .wasm
  jvm/  js/  native/                   empty platform shells
wasi/                                  cross-platform WASI Preview 1 shim (zero deps)
  shared/src/main/scala/.../wasi/      Wasi.preview1 + WasiContext + HostBackedPreopen
  jvm/    src/main/scala/.../wasi/     HostPreopen.fromDir   (java.nio.file + FileChannel)
  native/ src/main/scala/.../wasi/     HostPreopen.fromDir   (same surface as JVM)
  js/     src/main/scala/.../wasi/     HostPreopen.fromDir   (Node fs.*Sync)
  shared/src/test/                     WasiFd / WasiArgs / WasiClock / WasiFs / WasiHostFs / WasiRealRust tests
cli/                                   cross-platform CLI (depends on interp + wasi + scopt)
  shared/src/main/scala/.../cli/       Cli.scala (scopt config + dispatch)
  jvm/    src/main/scala/.../cli/      Main.scala (java.nio file read + HostPreopen plumbing)
  js/     src/main/scala/.../cli/      Main.scala (Node fs + process.argv + HostPreopen plumbing)
  native/ src/main/scala/.../cli/      Main.scala (java.nio + HostPreopen plumbing)
examples/
  hello.wat / hello.wasm               canonical Hello, world! module

How fixtures get into the test suite

Fixtures.scala is a generated Scala object exposing each committed .wasm binary as an Array[Byte]. It’s regenerated into each platform’s target/.../src_managed/test/ on every compile by a sourceGenerator in build.sbt, so it always derives from the committed binaries — no committed copy to drift.

Fixtures are base64-encoded string constants decoded once at class init. The previous Array[Byte](b0, b1, ...) literal form trips the JVM 64KB method-size limit on real-world fixtures like rustc-built wasi binaries; the base64 form sidesteps it.

To refresh a fixture from its .wat source, see Testing → Regenerating fixtures.

wasm

Validation

What the validator checks

What “fail at instantiate” looks like

Binary sections recognised

LEB128

What validation does not catch

Traps and errors

When each variant fires

InvalidModule is a dual-purpose variant

Worked example

WASI exit codes

Tracer

Tracer.Counting

Custom Tracer

From the CLI

What the tracer does NOT see

Lifetime + reuse

Testing

Unit suites

W3C testsuite

Regenerating fixtures

Syscalls

Process

Clock + entropy

Stdio + preopens

File I/O

Filesystem

Polling

Sockets

Spec compliance

Running it

How the pipeline works

Skipped commands

Known failures

What the runner caught

Recipes

Hand-written WAT, no WASI

Freestanding C, no libc

C with wasi-libc (<stdio.h>, argv, exit codes)

Real WASI binary with a host-backed preopen

Real WASI binary with file writes

Native CLI binary

Scala.js CLI (Node.js)

Inspecting a module without running it

Quickstart

1. Instantiate and invoke

2. Run a WASI command-mode binary

3. Customize the host environment

Where to go next

Preopens

Named preopens

In-memory preopens

Host-directory preopens

Picking a preopen kind

The Preopen trait surface

Opcodes

Numeric (all four scalar types)

Sign-extension proposal

Non-trapping float-to-int

Variables

Control flow

Tail calls

Exception handling

Legacy form

Modern try_table form

Tags

Memory

Passive vs active data + element segments

Reference types

Tables + functions

Stack

SIMD

The V128 value type (host side)

Foundations

Loads + stores

Lane access

Integer arithmetic

Shifts + min/max

Float arithmetic

`Tracer.Counting`

C with wasi-libc (`<stdio.h>`, argv, exit codes)

The `Preopen` trait surface

Modern `try_table` form

The `V128` value type (host side)

`<file>` (positional)

`<wasi-args>...` (trailing positional)

`-i`, `--invoke <export>`

`-a`, `--args n1,n2,...`

`--list-exports`

`-e`, `--env <key>=<value>`

`-p`, `--preopen <host-path>:<virtual-name>`

`--stdin <path>`

`--trace`

`--validate-only`

`--help` / `--version`

`WasiContext.default`

`WasiContext.collecting(...)`

The `Clock` trait

The `random` closure

The `sockets` field