⌘K
ENES
GitHub
indexWebAssembly Execution Model#webassembly#wat#bytecode#validation#sandboxing

WebAssembly Execution Model

WebAssembly is a portable, typed instruction format with an explicitly defined validation and execution model. It is not a small operating system, a JavaScript replacement, or a source language. A module declares code, data, imports, exports, tables, references, and memories; a host validates and instantiates that module, supplies its imports, and decides which external capabilities it receives.

Introduction and Mental Model

Think of a Wasm module as a sealed computation graph made from typed stack-machine instructions. Validation proves structural and type properties before execution. Instantiation binds imports, allocates runtime objects, evaluates initializers, and can run a start function. Execution may return values or trap; it cannot silently turn an out-of-bounds linear-memory access into an arbitrary host-memory access.

That isolation is only one layer of a security design. Wasm constrains module execution, while the embedding host controls authority through imports, resource limits, scheduling, and the surrounding runtime. A module handed a powerful filesystem, network, DOM, or native import can exercise that capability. The sandbox is therefore a combination of Wasm semantics and a deliberately narrow host contract.

This branch applies machine-level ideas from the Low-Level Atlas to Wasm's specified virtual machine. It does not repeat the general treatment of machine code, processes, or operating-system isolation found there.

Why It Matters

AI tooling can hide Wasm behind generated bindings and runtime APIs, but every later performance and correctness question eventually reaches this layer. A tensor pointer is an offset into a memory. A missing operator can become an import. A bounds error becomes a trap. A feature-dependent module may fail validation before its model ever loads. Understanding those transitions makes failures inspectable instead of mysterious.

Questions This Branch Answers

  • What information is present in the binary format, and what does WAT expose as a human-readable projection?
  • How does the operand stack differ from linear memory and from the host language's call stack?
  • Which type errors are rejected during validation, and which failures remain runtime traps?
  • What happens between WebAssembly.instantiate and the first exported function call?
  • How do functions, globals, tables, references, memories, imports, and exports fit into one module instance?
  • What can a module observe or affect without a corresponding host import?
  • How do indirect calls and tables preserve type checks at runtime?
  • Which properties come from the core specification, and which come from a particular browser or standalone runtime?

Scope

  • The core binary and text formats at the level needed to inspect and author small modules.
  • Numeric and reference value types, function signatures, locals, globals, and structured control flow.
  • Validation of instructions, control frames, functions, and modules.
  • Imports, exports, tables, references, linear memories, data segments, and element segments.
  • Instantiation, initialization order, exported calls, return values, and traps.
  • The boundary between core Wasm semantics and host-provided capabilities.
  • Feature detection and explicit compatibility checks for proposals or newer standardized features.

Out of Scope

  • Re-teaching general compiler construction, assembly language, virtual memory, or operating-system process isolation.
  • Treating WAT as the implementation language for the entire workbench.
  • Promising that every engine supports every proposal or the same resource limits.
  • WASI system interfaces, the Component Model, and the Canonical ABI beyond a short orientation; their contracts belong to later branches.
  • Production model runtimes, GPU acceleration, and neural-network operator implementation.

Expected Outcomes

After this branch, the reader should be able to:

  • Read a small WAT module and predict its validation, imports, exports, memory effects, result, and possible traps.
  • Inspect the sections and declarations of a .wasm binary without treating it as opaque compiler output.
  • Explain validation, instantiation, and execution as separate stages with separate failure modes.
  • Design a minimal host contract instead of granting ambient capabilities by accident.
  • Distinguish core-spec behavior from JavaScript API behavior and runtime-specific behavior.
  • Build the first visible Wasm milestone of the WasmAI Workbench from a handwritten module.

Candidate Note Roadmap

  • binary-format-and-wat-round-trips — inspect magic/version bytes and sections, translate between WAT and Wasm, and identify what text formatting does not preserve.
  • typed-stack-machine-and-structured-control — trace operands, locals, blocks, loops, branches, and function results instruction by instruction.
  • validation-before-execution — construct invalid modules for stack, label, function, memory, and feature errors, then separate validation failures from traps.
  • modules-imports-exports-and-instances — follow a module from declarations through import matching, instantiation, initialization, and exported calls.
  • linear-memory-data-segments-and-addresses — map byte offsets to loads and stores, alignment hints, bounds checks, data initialization, and growth.
  • tables-references-and-indirect-calls — explain funcref values, element segments, typed indirect calls, null references, and runtime checks.
  • traps-start-functions-and-failure-surfaces — catalog arithmetic, conversion, memory, table, call, and initialization failures with observable host behavior.
  • capabilities-and-the-real-sandbox-boundary — audit imports, denial by omission, resource limits, and why isolation does not make untrusted host callbacks safe.

Future Runnable Artifact

WasmAI Workbench v0 will include a handwritten WAT module and a TypeScript host with no generated bindings. The module will export one linear memory plus affine_relu(input_ptr, output_ptr, length, scale, bias). A scalar loop will load each little-endian f32, compute max(0, input * scale + bias), and store the result at a non-overlapping output range.

The host will validate and instantiate the binary, write deterministic inputs through a Float32Array view, invoke the export, read the result, and compare it with a TypeScript reference. The artifact will also retain the WAT, generated .wasm, section dump, import/export inventory, and deliberately invalid and trapping fixtures. It will expose every offset and byte length in the UI so that the first milestone makes module structure and linear memory visible rather than abstracting them away.

How to Verify and Measure

  • Round-trip the module with WABT tools and inspect sections with wasm-objdump; compare semantics rather than assuming byte-for-byte identity after a text round-trip.
  • Require wasm-validate and WebAssembly.validate to accept the valid module and reject versioned invalid fixtures for documented reasons.
  • Compare every output element with the TypeScript reference using recorded absolute and relative tolerances, including empty, single-element, negative, NaN, and infinity cases.
  • Trigger documented out-of-bounds and indirect-call failures and assert that they trap without a partial success being reported.
  • Inventory imports and exports automatically; the v0 module should have no undeclared environmental dependency.
  • Measure fetch/read, validation/compilation, instantiation, first call, and warmed steady-state calls separately. Record browser or runtime version, CPU, module hash, and feature flags with the result.
  • Report raw, gzip, and Brotli module sizes separately from TypeScript host bytes.

Primary Sources

  • WebAssembly Core Specification — normative core syntax, validation, execution, binary, and text formats. Release 3.0; checked 2026-07-16.
  • WebAssembly JavaScript Interface — normative integration model for modules, instances, memories, tables, and JavaScript values. Living Editor's Draft dated 2026-07-10; checked 2026-07-16.
  • WebAssembly Web API — browser fetching, compilation, and streaming integration. Living specification; checked 2026-07-16.
  • WebAssembly feature status — implementation matrix and links to proposal stages; changing compatibility data, checked 2026-07-16.
  • WebAssembly Binary Toolkit — primary implementation source for wat2wasm, wasm2wat, wasm-validate, and inspection tools. Active project; checked 2026-07-16.

Connects to: Toolchains and Language Targets · Linear Memory, ABI, and Host Interop · Tensor Kernels and Inference from Scratch · Sandboxed AI Tools and Plugins · Wasm AI Performance, Security, and Craftsmanship