WebAssembly: implement the MVP runtime and JavaScript API

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.

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.

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.

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.

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.

Published the asynchronous JS API checkpoint to main:

• runtime: 2374c537 (feat(wasm): add asynchronous compile and instantiate (#141))
• documentation: 95c01e93 (docs(wasm): publish Promise API evidence (#141))
• focused WebAssembly suite: 120/120 passed
• result: 0 skipped, 0 failed, 0 leaked

WebAssembly.compile and both WebAssembly.instantiate overloads now snapshot BufferSource bytes before returning, queue rooted native work, return Promises without synchronous throws for conversion/compile failures, preserve TypeError/CompileError/LinkError rejection classes, delay import getter access until queued instantiation, and return either Instance or { module, instance } according to the overload. The synchronous Instance constructor now also rejects primitive/null import objects and reports a missing required imports object as TypeError.

The remaining acceptance gate has been split into #260: pin, run, and publish a machine-readable upstream wg-1.0 specification corpus inventory. #141 stays open until that inventory has no unaccounted applicable MVP failures.

The WebAssembly MVP runtime and JavaScript API are complete on main.\n\nThe decoder, validator, interpreter, Module/Instance/Memory/Table/Global/Function surface, all import/export kinds, segments/start/linking/traps, Promise compile and both instantiate overloads, error classes, GC ownership, and failure-atomic store behavior are implemented.\n\nCurrent evidence:\n- focused WebAssembly suite: 122/122 pass, 0 skip/fail/leak;\n- full engine suite: 1,002/1,002 pass, 0 skip/fail/leak;\n- upstream wg-1.0 corpus: 16,801/16,801 JavaScript-observable commands pass across 73 files, 0 failures, 0 runner errors;\n- all 19,270 upstream commands have explicit inventory entries;\n- README.md and docs/wasm.md were refreshed in 2bbe78d.\n\n#261 remains open as a supplemental direct bit-exact runner for NaN payload/sign assertions that the JavaScript Number boundary cannot observe; those cases are explicit and issue-linked, not hidden exclusions or MVP runtime failures.

Final corpus follow-up: #261 is complete, so all 18,840 applicable wg-1.0 binary-runtime commands now pass. The remaining 430 of 19,270 inventory entries are solely text-format parser assertions outside the JavaScript binary API; there are 0 engine failures and 0 runner errors.

Two remaining evidence pieces from the original implementation plan are now on main:

• 8f1c3b91 — packed upstream runner zig build wasm-spec: the pinned wg-1.0 corpus ships as checked-in artifacts (tests/wasm/spec/{manifest.json,modules.bin,inventory.json}), executes every directive through the public JavaScript WebAssembly API with per-file subprocess isolation (120 s watchdog), and reproduces offline with no WABT build. Inventory: 73 files, 18,791 pass, 0 fail, 479 classified skips, 0 crash. Skip taxonomy: 430 wat-text assert_malformed (text format is outside the binary API), 40 NaN payload/sign expectations (unobservable across the JS Number boundary — scored exactly by the #261 bit-exact runner), 4 generator rejects, 5 deliberate Core 2.0 policy divergences (V8-matching, unit-test-locked). Verified byte-identical against the checked-in inventory at current HEAD.
• 3ec6c7b6 — direct workers evidence: WebAssembly.Module / Instance / validate compile, instantiate, and execute inside a Worker context with the result round-tripping to the parent, giving the workers integration bullet its own test.
• 30df2aa6 — docs/wasm-spec.md documents the packed pipeline: pin, regeneration (tools/wasm-spec/fetch.sh + gen.mjs), skip taxonomy, and the error-text alias policy (only the error class is normative; text is implementation-defined). It complements the #260/#261 evaluator documented in docs/wasm.md.

With #260 and #261 complete (18,840/18,840 applicable commands) and this packed runner green, every acceptance bullet has direct checked-in evidence.

CI follow-up: the wasm-mvp-smoke gate in .github/workflows/ci.yml invoked zig build wasm-spec with -Dwast2json / -Dwasm-spec-inventory, which the packed runner's build step never declared — the step hard-failed with error: invalid option on every run. Fixed in 57649e31 without touching the workflow file (this token lacks the workflow scope): the build step now accepts -Dwast2json (unused — the packed artifacts embed converter output, so no converter exists at run time) and -Dwasm-spec-inventory as an alias of -Dwasm-spec-out. The gate's exact original commands were re-run locally and pass: linking.wast 114 pass / 0 fail / 4 classified skips, f32_bitwise.wast 348 pass / 0 fail / 16 classified skips. The stale copy of that command in docs/wasm.md was replaced with the two working invocations (live-WABT evaluator via wasm-spec-eval + tools/wasm-spec.py --profile mvp, and the packed zig build wasm-spec).

Created #406 for the next coherent boundary: real WebAssembly.compileStreaming/instantiateStreaming plus the pinned JSC__Wasm__StreamingCompiler__addBytes opaque feed. It explicitly preserves the frozen WG1 baseline while validating modern coverage through the existing WG3 and upstream-main profiles.

#407 is implemented on main through a35f025e. Fetch bodies now preserve real streams, derive bodyUsed from disturbance, share all six #405 conversions, and tee live bodies for Response/Request cloning with combined cancellation. Focused Debug, ReleaseSafe, and TSan evidence passes; exact main CI is pending before closure.