globals: complete standard WebAssembly namespace surface

[andrewtdiz]

Summary

PR #705 closed #76 by landing a useful WebAssembly host PoC, but the shipped API is still a Perry-specific synchronous subset. Current Node exposes the standard global WebAssembly namespace object, with constructor classes, async compile/instantiate methods, streaming methods, and typed error constructors. Perry currently recognizes a few WebAssembly.* call shapes syntactically instead of exposing a Node-compatible namespace value.

This is observable to packages that feature-detect globalThis.WebAssembly, destructure methods/classes, construct WebAssembly.Module / WebAssembly.Instance, catch WebAssembly.CompileError, or rely on the standard Promise-returning instantiate() shape used by wasm-pack/emscripten glue.

Expected Node behavior

Node's WebAssembly guide says Node provides the necessary APIs via the global WebAssembly object: https://nodejs.org/en/learn/getting-started/nodejs-with-webassembly

A local Node v25.9.0 probe shows the namespace shape:

typeof WebAssembly object
global identity true
keys CompileError,Exception,Global,Instance,JSTag,LinkError,Memory,Module,RuntimeError,SuspendError,Suspending,Table,Tag,compile,compileStreaming,instantiate,instantiateStreaming,promising,validate
Module proto function constructor
Instance proto function constructor,exports

Probe:

console.log("typeof WebAssembly", typeof WebAssembly);
console.log("global identity", globalThis.WebAssembly === WebAssembly);
console.log("keys", Object.getOwnPropertyNames(WebAssembly).sort().join(","));
console.log("Module proto", typeof WebAssembly.Module, Object.getOwnPropertyNames(WebAssembly.Module.prototype).sort().join(","));
console.log("Instance proto", typeof WebAssembly.Instance, Object.getOwnPropertyNames(WebAssembly.Instance.prototype).sort().join(","));

Node's standard WebAssembly.instantiate(bufferSource[, importObject]) returns a Promise for raw bytes and supports new WebAssembly.Module(bytes) plus new WebAssembly.Instance(module, imports) for synchronous construction.

Current Perry evidence

Source inspection against origin/main:

• crates/perry-runtime/src/webassembly.rs explicitly documents the current surface as MVP API (Perry-specific, not standard).
• The same comment says the PoC exposes only three synchronous top-level namespace builtins: WebAssembly.validate(bytes), WebAssembly.instantiate(bytes) returning an opaque handle, and WebAssembly.callExport(handle, name, ...).
• crates/perry-hir/src/lower/expr_call/module_static.rs only recognizes validate, instantiate, and the nonstandard callExport when the receiver is the identifier WebAssembly.
• crates/perry-runtime/src/object/global_this.rs::GLOBAL_THIS_BUILTIN_NAMESPACES does not include WebAssembly, so globalThis.WebAssembly is not populated through the native global singleton path.
• crates/perry-codegen/src/expr/helpers.rs::is_global_this_builtin_name() also omits WebAssembly, so globalThis.WebAssembly reads do not route to a populated namespace object.
• test-files/test_wasm_add.ts only covers the PoC flow: WebAssembly.validate(bytes), sync WebAssembly.instantiate(bytes), and inst.exports.add(...); it does not cover globalThis.WebAssembly, constructors, error classes, Promise shape, or imports object behavior.

I did not run a Perry binary because this checkout does not have target/release/perry; this issue is based on committed origin/main source, current Node docs, and a local Node v25.9.0 probe.

Suggested test surface

Add parity tests for the standard namespace shape separately from the existing PoC test:

console.log(typeof globalThis.WebAssembly === "object");
console.log(globalThis.WebAssembly === WebAssembly);
for (const k of [
  "validate",
  "compile",
  "instantiate",
  "compileStreaming",
  "instantiateStreaming",
  "Module",
  "Instance",
  "Memory",
  "Table",
  "Global",
  "CompileError",
  "LinkError",
  "RuntimeError",
]) {
  console.log(k, typeof WebAssembly[k]);
}

Add behavior tests for:

• WebAssembly.instantiate(bytes) returning a Promise resolving to { module, instance } for raw bytes.
• new WebAssembly.Module(bytes) and new WebAssembly.Instance(module, imports).
• instance.exports.<name> working without compile-time-only local tagging assumptions.
• invalid bytes throwing/rejecting with WebAssembly.CompileError.
• importObject plumbing for numeric host imports once supported.

Scope / non-goals

This issue is a completion follow-up for the standard Node/global WebAssembly API shape after #76/#705. It should not remove the existing PoC helper path unless maintainers decide to deprecate it; WebAssembly.callExport can remain Perry-specific if useful, but it should not be the only way to call exports.

Streaming methods can initially throw or reject with a clear unsupported error if Perry lacks Response body streaming, but the namespace and function/class presence should match Node closely enough for feature detection.

Duplicate search

Checked existing issues and PRs with:

• WebAssembly global
• WebAssembly validate instantiate globalThis
• WebAssembly Module Instance Memory Table
• WebAssembly instantiate validate wasmi

The hits were closed #76 and merged #705, both of which explicitly shipped the PoC subset and list the standard async surface, imports, streaming methods, and host passthrough as follow-up work. I did not find an open tracker for the Node-compatible namespace object and standard constructor/method surface.

[andrewtdiz]

Fresh local evidence from the Node API compatibility sweep. Current origin/main is build-red at d4f2903fa567 (#3864), so this was verified on the previous buildable main:

aed3a2b1b985 chore: complete stream tasklist reconciliation (#3790)

The curated globals suite reaches the WebAssembly metadata fixture and then stalls while Perry is compiling it:

./run_parity_tests.sh --suite node-suite --module globals

Observed stuck compile process before I killed it:

target/release/perry test-parity/node-suite/globals/webassembly-module-metadata.ts -o /tmp/perry_parity_node-suite__globals__webassembly-module-metadata

That fixture exercises the standard Node/WebAssembly namespace, not Perry-specific wasm helpers:

WebAssembly.validate(bytes)
new WebAssembly.Module(bytes)
WebAssembly.Module.exports(module)
WebAssembly.Module.imports(module)
WebAssembly.Module.customSections(module, "meta")
await WebAssembly.compile(bytes)

So the current issue is still not only namespace shape; standard WebAssembly.Module metadata and async WebAssembly.compile() are not yet far enough through Perry to produce a parity diff.

[andrewtdiz]

Current-main retest at 22824ba90 updates this from “stall while compiling” to a concrete link-time failure.

Globals suite summary:

$ ./run_parity_tests.sh --suite node-suite --module globals
Parity Pass:   31
Parity Fail:   1
Compile Fail:  1
Report: /private/tmp/perry-node-compat-main/test-parity/reports/parity_report_20260531_145303.json

The failing WebAssembly fixture is still node-suite/globals/webassembly-module-metadata, which Node runs successfully:

validate add: true
exports add: add:function
imports fn: env.f:function
custom meta count: 1
custom meta bytes: 1,2,3
custom missing count: 0
compile exports: add:function

Perry first failed with:

Error: WebAssembly.* used but libperry_wasm_host.a not found. Build it with: cargo build --release -p perry-wasm-host

After building perry-wasm-host, the same fixture still cannot link, even with --enable-wasm-runtime:

Using wasmi WebAssembly host runtime
Undefined symbols for architecture arm64:
  "_js_webassembly_compile"
  "_js_webassembly_module_custom_sections"
  "_js_webassembly_module_exports"
  "_js_webassembly_module_imports"
  "_js_webassembly_module_new"
  "_js_webassembly_validate"
ld: symbol(s) not found for architecture arm64
Error: Linking failed

The helper archive exports perry_wasm_host_* C ABI symbols, while the generated object references js_webassembly_* symbols. That points to a missing runtime shim/link path for the standard WebAssembly namespace metadata APIs before we can even compare runtime output.

No Test262 coverage was involved; this is Node/global API compatibility evidence only.

[proggeramlug]

Implemented by #3635 / #3653 (merged, on main): the standard WebAssembly namespace surface (Module/Instance/Memory/Table/Global, error classes, validate/instantiate/compile).