WebAssembly: implement the MVP runtime and JavaScript API

[chrisbbreuer]

Parent: #134

Implement a correct WebAssembly MVP end to end.

Acceptance:

• Decode and validate modules with deterministic diagnostics.
• Compile/execute MVP instructions, functions, control flow, numeric operations, memory, tables, globals, imports, exports, start functions, and traps.
• Implement WebAssembly.Module, Instance, Memory, Table, Global, CompileError, LinkError, and RuntimeError behavior.
• Integrate calls, exceptions, GC roots, workers, and shared-runtime teardown.
• Run the applicable upstream WebAssembly spec tests with a machine-readable pass/fail/skip inventory.
• Do not silently accept unsupported proposal opcodes or sections.

[chrisbbreuer]

Taking this one. Implementation plan:

Architecture (all inside src/wasm/, wired into the engine via the established builtin patterns):

• types.zig — module IR (types, imports, exports, globals, elems, datas, code) shared by every stage.
• decode.zig — binary decoder: strict LEB128, section-order enforcement, per-instruction byte offsets, and deterministic diagnostics (CompileError carries byte offset + stable message). Unknown section ids and non-MVP opcodes/prefixes (0xFC/0xFD/0xFE/0xFB, reference-types, datacount) are hard errors — nothing silently accepted.
• validate.zig — full MVP type-checking (value stack + control frames), same deterministic diagnostic channel.
• exec.zig — interpreter over a jump-patched instruction array: frames, labels, calls/call_indirect with exact signature match, all MVP numeric ops, memory/table/global access, traps (RuntimeError), start.
• api.zig — JS surface: WebAssembly namespace with Module (+imports/exports/customSections), Instance, Memory, Table, Global, validate/compile/instantiate, and CompileError/LinkError/RuntimeError as own properties of the namespace with correct Error prototype chains. Exported functions marshal i32/f32/f64 via ToNumber, i64 via BigInt; import calls go through callValueWithThis so JS exceptions propagate.
• Integration: new ObjectRareTags traced in gc.zig (instance → module/memories/tables/globals/import values), memory growth detaches the old ArrayBuffer per spec, per-context store torn down in Context.destroy, wasm usable inside workers.

Testing / evidence:

• Zig unit tests per stage (zig build test -Dtest-filter=wasm).
• Upstream spec suite pinned at the wg-1.0 tag of WebAssembly/spec (pure MVP — current main mixes in post-MVP proposals), converted via a checked-in generator (tools/wasm-spec-gen, bun + wabt) into packed artifacts under tests/wasm/spec/.
• New zig build wasm-spec runner executes every directive through the real JS API and emits a machine-readable pass/fail/skip inventory at docs/wasm/spec-inventory.json. Skips are explicit and categorized (wat-text-only assert_malformed cases we cannot express as binary); no hidden exclusions.

Landing as small conventional commits on main tagged (#141): decoder → validator → exec → JS API → integration → spec runner → docs evidence.

[chrisbbreuer]

First JS-facing checkpoint is now on main:

• 1296dd80 adds the WebAssembly namespace, correctly chained CompileError / LinkError / RuntimeError, new WebAssembly.Module(BufferSource), WebAssembly.validate, and Module.imports / exports / customSections.
• Module bytes are snapshotted, decoded/validated data is context-owned and deterministically torn down, custom sections are copied, and invalid/detached/out-of-bounds inputs have explicit boundaries.
• The focused decoder + validator + executor + JS API suite passes 110/110 with zero leaks.
• 88316c5f publishes the status and reproduction command in README/docs without claiming the JS store API or upstream spec corpus is complete.

Still open in this issue: JS-facing Instance/Memory/Table/Global/exported functions, linking and JS/Wasm boundaries, compile/instantiate Promise APIs, and the pinned upstream MVP spec inventory.

[chrisbbreuer]

Second JS/store checkpoint is on main:

• 2736cf71 adds WebAssembly.Memory and WebAssembly.Global.
• Memory exposes the native store bytes zero-copy, grows failure-atomically, preserves and zero-fills bytes, detaches/empties the old buffer, publishes a new identity, and prevents JS/structured-clone/test-host transfer of live Memory backing. Precise-GC retention and context teardown are covered.
• Global covers mutable/immutable i32/i64/f32/f64, ToNumber/ToBigInt and modulo boundaries, signed reads, valueOf/numeric coercion, branding, and derived constructors.
• Generated native ArrayBuffer handles explicitly reject growable Memory backing until a stable grow-aware handle contract exists, preventing stale native pointers.
• Focused WebAssembly evidence is now 113/113 with zero failures, skips, or leaks.
• 46eaf281 updates README and docs/wasm.md; the validated 1,540-sample benchmark remains current because these APIs are outside its workloads.

Next coherent slice: Table together with Instance/import-export and exported-function identity. #141 remains open.

[chrisbbreuer]

Published the Instance/Table/linking checkpoint to main:

• runtime: 0835f411 (feat(wasm): link instances and tables (#141))
• documentation: 3265fd6a (docs(wasm): publish Instance and Table evidence (#141))
• focused WebAssembly suite: 118/118 passed
• batched full engine suite: 998/998 passed
• both runs: 0 skipped, 0 failed, 0 leaked

This slice provides WebAssembly.Instance and WebAssembly.Table, all four import/export kinds, defined/imported store identity, start functions, active data/element segments, callable exports/imports, JS/Wasm numeric conversion, exception identity, indirect calls, and RuntimeError traps. README and docs/wasm.md now describe the shipped surface and retain the current benchmark matrix because these APIs do not execute in its workloads.

Remaining before #141 closes: Promise-correct WebAssembly.compile and both WebAssembly.instantiate overloads, plus the pinned upstream MVP corpus/inventory.