Wasm Support

hugr-qir supports lowering programs that use the Wasm extension and refer to functions in a provided Wasm module.

Currently, the only supported guppylang Wasm platform is WasmPlatform.H2. This is not the default and must be explicitly set as a parameter to the guppylang @wasm_module decorator.

Only a single Wasm context is supported. guppylang.std.qsystem.spawn_wasm_contexts is not supported, and the context is created by constructing the decorated Wasm module class with MyWasm(nat(1)) (see Examples: Wasm integration).

In the compiled Wasm file, the only supported function parameter type is a 32-bit integer. A Wasm file may still contain unsupported functions, as long as the Guppy program does not call them.

Providing a Wasm file

Python:

qir = hugr_to_qir(hugr_package, wasm_file=Path("module.wasm"))

CLI:

hugr-qir input.hugr --wasm-file module.wasm

Signature validation

When a Wasm function is referenced, the backend checks:

  • the requested input arity matches the Wasm signature

  • the requested output arity matches the Wasm signature

  • Wasm parameters must be i32

  • Wasm results must have length <= 1

  • a single Wasm result, if present, must be i32

  • the requested HUGR-side integer types may use i64 where the Wasm signature uses i32

This validation is intentionally deferred until lookup time, so unrelated functions in the same Wasm file do not cause compilation to fail.

Missing functions

If a lookup references a function that is not present in the provided Wasm file, the error message includes the lookup target and, when available, the Wasm filename.