feat(codegen): wasm32 WASI lowering behind off-by-default target-wasi (WASI phase 3b)

.github/workflows/wasi-check.yml

@@ -1,8 +1,13 @@
 name: WASI Check
 
-# Keeps `perry-runtime` building for the standalone WASI target
-# (wasm32-wasip2). Tracking issue #11375; this gate is phase 2a (#11377).
-# The check itself is `scripts/wasi_check.sh` — run it locally the same way.
+# The standalone WASI target (wasm32-wasip2), tracking issue #11375:
+#   wasi-check     `perry-runtime` builds for WASI (phase 2a, #11377;
+#                  `scripts/wasi_check.sh`) and the runtime ABI checks.
+#   wasi-codegen   a compiler built with `--features target-wasi` compiles
+#                  sample programs for WASI and every runtime call in the IR
+#                  matches the runtime's signature (#11378;
+#                  `scripts/wasi_ir_check.sh`).
+# Both scripts run locally the same way.
 #
 # Checked against CLAUDE.md's "four ways a gate can be unable to fail":
 #
@@ -28,10 +33,21 @@ on:
     paths:
       - "crates/perry-runtime/**"
       - "crates/perry-dispatch/**"
+      # The ABI table is built from the runtime, stdlib and ext crates, and
+      # the codegen job builds the perry driver and compiles gap programs.
+      - "crates/perry-stdlib/**"
+      - "crates/perry-ext-*/**"
+      - "crates/perry/**"
+      - "crates/perry-codegen/Cargo.toml"
+      - "test-files/test_gap_*.ts"
+      - ".github/actions/setup-llvm22/**"
+      - "Cargo.toml"
+      - ".cargo/**"
       - "Cargo.lock"
       - "rust-toolchain.toml"
       - "scripts/wasi_check.sh"
       - "scripts/runtime_abi_check.py"
+      - "scripts/wasi_ir_check.sh"
       - "crates/perry-codegen/src/**"
       - ".github/workflows/wasi-check.yml"
   # Main-line arm: one daily sweep, not one run per merge — see
@@ -78,3 +94,34 @@ jobs:
         run: python3 scripts/runtime_abi_check.py --self-test
       - name: Runtime ABI check (report)
         run: python3 scripts/runtime_abi_check.py
+      # The wasm32 lowering adapts calls to the runtime's real signatures as
+      # recorded in this table; a stale table would adapt to the wrong ones.
+      - name: wasm32 runtime ABI table is current
+        run: python3 scripts/runtime_abi_check.py --check-wasm-abi
+
+  # The wasm32 codegen lowering (#11378), in a compiler built with the
+  # off-by-default `target-wasi` feature: sample programs compile for WASI and
+  # every runtime call in the emitted IR matches the runtime's real signature.
+  wasi-codegen:
+    if: github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'run-extended-tests')
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install Rust toolchain
+        run: rustup toolchain install nightly-2026-08-20 --profile minimal
+      - uses: ./.github/actions/setup-llvm22
+
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+        with:
+          shared-key: "${{ runner.os }}-wasi-codegen"
+          save-if: ${{ github.ref == 'refs/heads/main' }}
+
+      - name: Build perry with the WASI target
+        run: cargo build --locked --profile perry-dev -p perry --features target-wasi
+
+      - name: wasm32 IR matches the runtime ABI
+        run: ./scripts/wasi_ir_check.sh target/perry-dev/perry

changelog.d/11406-wasi-codegen-lowering.md

@@ -0,0 +1,23 @@
+Perry can emit wasm32 code for the standalone WASI target (`--target wasi`,
+`wasm32-unknown-wasip2`) when the compiler is built with the new,
+off-by-default `target-wasi` cargo feature (phase 3b of #11375, #11378).
+Without the feature nothing compiles differently. With it, only wasm32 WASI
+takes any new path; host IR from a baseline, the default build and a
+`target-wasi` build is otherwise unchanged (125/130 gap modules byte-identical,
+and the rest differ only in an ordering the baseline itself varies).
+
+- A wasm32-only pass rewrites each runtime declaration to the runtime's real
+  signature. Every call whose own type differs goes through an inlined adapter.
+  On LP64, codegen's i64-for-pointer convention matches the runtime; on wasm32
+  it would be a link-time signature mismatch at ~1,200 sites.
+- The signatures come from `crates/perry-codegen/src/wasm32/runtime_abi.tsv`.
+  `scripts/runtime_abi_check.py --emit-wasm-abi` generates it from the runtime
+  source, and `--check-wasm-abi` checks it is current.
+- The shadow-frame push reads the 32-bit `frame_top` on wasm32.
+- Inline shadow-slot stores, the Map entry fast path and inline arena
+  allocation take their runtime calls on wasm32.
+
+`runtime_abi_check.py --ir` verifies emitted wasm32 IR (27,946 runtime calls
+across 54 gap modules, 0 mismatches). `scripts/wasi_ir_check.sh` runs it on
+sample programs in the non-required `wasi-check` workflow's new
+`wasi-codegen` job. Linking a `.wasm` is phase 4 (#11379).

crates/perry-codegen/Cargo.toml

@@ -27,6 +27,11 @@ workspace = true
 # `--no-default-features` still builds the text path for bisection.
 default = ["llvm-inprocess"]
 llvm-inprocess = ["dep:inkwell", "dep:llvm-sys"]
+# Standalone WASI target (wasm32-wasip2, #11375/#11378). OFF BY DEFAULT: it
+# links LLVM's WebAssembly backend into the compiler and enables the wasm32
+# lowering (runtime ABI adapters, ILP32 layouts). With it off, nothing about
+# any other target's output changes — and every wasm32 path below is behind it.
+target-wasi = ["llvm-inprocess", "inkwell?/target-webassembly"]
 
 # Test-support only (#7493): exposes `perry_codegen::testing`, whose
 # `NativeRootsPin` lets a test declare WHICH root lowering it asserts on. It is

crates/perry-codegen/src/codegen/helpers.rs

@@ -244,6 +244,23 @@ pub(crate) fn set_native_roots_for_target(triple: &str) {
     NATIVE_ROOTS_TARGET_OK.with(|c| c.set(arch_ok && windows_ok));
 }
 
+thread_local! {
+    static ILP32_TARGET: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
+}
+
+/// Record, per module, whether this compile targets 32-bit pointers. Only the
+/// wasm32 WASI lowering can get here with `true` (`compile_module` refuses
+/// every other ILP32 triple), so on every other target the inline paths that
+/// consult [`ilp32_target`] emit exactly what they always did.
+pub(crate) fn set_ilp32_for_target(triple: &str) {
+    ILP32_TARGET.with(|c| c.set(crate::target_layout::target_is_ilp32(triple)));
+}
+
+/// See [`set_ilp32_for_target`].
+pub(crate) fn ilp32_target() -> bool {
+    ILP32_TARGET.with(|c| c.get())
+}
+
 /// Whether precise roots should use a native-stack metadata backend rather
 /// than Perry's heap-backed shadow frame.
 pub(crate) fn native_stack_roots_enabled() -> bool {
@@ -1287,6 +1304,9 @@ pub fn resolve_target_triple(name: &str) -> Option<String> {
         }
         "watchos" => Some("aarch64-apple-watchos".to_string()),
         "watchos-simulator" => Some("arm64-apple-watchos10.0-simulator".to_string()),
+        // Standalone WASI (#11375): only a compiler built with `target-wasi`
+        // knows the name; a default build keeps resolving it to None.
+        "wasi" if cfg!(feature = "target-wasi") => Some("wasm32-unknown-wasip2".to_string()),
         "tvos" => Some("aarch64-apple-tvos".to_string()),
         "tvos-simulator" => Some("arm64-apple-tvos17.0-simulator".to_string()),
         "harmonyos" => Some("aarch64-unknown-linux-ohos".to_string()),

crates/perry-codegen/src/codegen/mod.rs

@@ -454,6 +454,9 @@ pub fn compile_module(hir: &HirModule, opts: CompileOptions) -> Result<Vec<u8>>
     // Native roots are the default lowering wherever the runtime can walk the
     // frames, and the shadow stack elsewhere. Same per-module discipline.
     helpers::set_native_roots_for_target(&triple);
+    // ILP32 (wasm32 WASI only): inline paths that bake in LP64 layouts take
+    // their runtime-call arms or ILP32 offsets. Same per-module discipline.
+    helpers::set_ilp32_for_target(&triple);
 
     // `--opt-report` (#6952): mark the closures that are iterating-builtin
     // callbacks before any region is lowered, so their denials carry the
@@ -3779,7 +3782,15 @@ pub fn compile_module(hir: &HirModule, opts: CompileOptions) -> Result<Vec<u8>>
     // behavior). `emit_ir_only` wants the whole-module text, so it takes the
     // single-text path; the split path avoids materializing the full ~1GB IR
     // string at all (which would defeat the memory win).
-    let n_units = if opts.emit_ir_only {
+    // wasm32 WASI (#11378) takes the single-text path: its runtime-ABI pass
+    // rewrites the whole module text before object emission. Splitting it
+    // needs more than per-unit adaptation: the unit objects must be combined
+    // with `wasm-ld -r` (the host `ld -r` cannot read wasm), each trimmed of
+    // the buffer's trailing NUL, and the closure-ABI rewrite needs the
+    // module-wide set of closure bodies. Until then a large WASI module is
+    // compiled as one unit.
+    let wasm32 = crate::target_layout::wasm32_lowering(&triple);
+    let n_units = if opts.emit_ir_only || wasm32 {
         1
     } else {
         decide_codegen_units(
@@ -3834,14 +3845,22 @@ pub fn compile_module(hir: &HirModule, opts: CompileOptions) -> Result<Vec<u8>>
     // textual); `=diff` builds both arms and diffs them. Unit-split and
     // emit_ir_only paths above stay textual (they fall into the in-process
     // *transport* under these values, so no clang subprocess either way).
-    if let Some(result) =
-        try_native_construction(&mut llmod, opts.target.as_deref(), &module_prefix)
-    {
-        return result;
+    if !wasm32 {
+        if let Some(result) =
+            try_native_construction(&mut llmod, opts.target.as_deref(), &module_prefix)
+        {
+            return result;
+        }
     }
 
     loop {
         let ll_text = llmod.to_ir();
+        #[cfg(feature = "target-wasi")]
+        let ll_text = if wasm32 {
+            crate::wasm32::adapt_runtime_abi(&ll_text)
+        } else {
+            ll_text
+        };
         log::debug!(
             "perry-codegen: emitted {} bytes of LLVM IR for '{}' ({} interned strings)",
             ll_text.len(),

crates/perry-codegen/src/expr/array_literal.rs

@@ -165,7 +165,9 @@ pub(crate) fn emit_array_from_lowered_values(
     // Inline bump-allocator path for small literals. Size threshold matches
     // `MAX_SCALAR_ARRAY_LEN` in collectors.rs so every candidate the escape
     // pass rejects can still benefit from the inline alloc.
-    if n <= INLINE_ARRAY_MAX_ELEMENTS {
+    // ILP32 (wasm32 WASI, #11378): the inline bump reads `InlineArenaState`
+    // at LP64 offsets; take the runtime call below instead.
+    if n <= INLINE_ARRAY_MAX_ELEMENTS && !crate::codegen::helpers::ilp32_target() {
         // Layout constants — must match `ArrayHeader` in array.rs and
         // `GcHeader` in gc.rs. Duplicated here because codegen emits raw
         // byte offsets; the runtime declarations are authoritative.

crates/perry-codegen/src/expr/arrays_finds.rs

@@ -139,6 +139,14 @@ fn lower_map_entry_at_inline(
         let is_pointer = blk.icmp_eq(I64, &top16, POINTER_TAG_TOP16_I64);
         let above_band = blk.icmp_ugt(I64, &m_handle, HANDLE_BAND_TOP);
         let plausible = blk.and(I1, &is_pointer, &above_band);
+        // ILP32 (wasm32 WASI): the header reads below use LP64 offsets
+        // (`MAP_HEADER_USED_OFFSET`, an i64 `entries`); every read takes the
+        // runtime helper instead, and LLVM drops the dead fast path (#11378).
+        let plausible = if crate::codegen::helpers::ilp32_target() {
+            "false".to_string()
+        } else {
+            plausible
+        };
         blk.cond_br(&plausible, &head_label, &slow_label);
         (m_handle, i_i32)
     };

crates/perry-codegen/src/expr/shadow_inline.rs

@@ -115,6 +115,11 @@ fn emit_inline_slot_write(ctx: &mut FnCtx<'_>, slot_idx: u32, what: InlineSlotWr
     if !crate::codegen::helpers::inline_shadow_slot_enabled() {
         return false;
     }
+    // ILP32 (wasm32 WASI): the inline sequence below reads LP64 offsets and
+    // i64 words; take the `js_shadow_slot_*` call arm instead (#11378).
+    if crate::codegen::helpers::ilp32_target() {
+        return false;
+    }
     let Some(state_slot) = ctx.func.shadow_state_slot().map(str::to_owned) else {
         return false;
     };

crates/perry-codegen/src/function.rs

@@ -224,6 +224,26 @@ fn shadow_frame_handle_lines(
     handle_reg: &str,
 ) -> Vec<String> {
     use crate::expr::shadow_inline::{SHADOW_STACK_HEADER_SLOTS, SHADOW_STATE_FRAME_TOP_OFFSET};
+    if crate::codegen::helpers::ilp32_target() {
+        // ILP32 (wasm32 WASI, #11378): `ShadowStackState`'s words are 4
+        // bytes, so `frame_top` is the fourth-byte-aligned word at 3 * 4 and
+        // is widened to the i64 handle every other use expects.
+        let top32 = format!("{top_reg}.w");
+        return vec![
+            format!("  store ptr {}, ptr {}", state_reg, state_slot),
+            format!(
+                "  {} = getelementptr inbounds i8, ptr {}, i64 12",
+                top_ptr_reg, state_reg
+            ),
+            format!("  {} = load i32, ptr {}", top32, top_ptr_reg),
+            format!("  {} = zext i32 {} to i64", top_reg, top32),
+            format!(
+                "  {} = sub i64 {}, {}",
+                handle_reg, top_reg, SHADOW_STACK_HEADER_SLOTS
+            ),
+            format!("  store i64 {}, ptr {}", handle_reg, handle_slot),
+        ];
+    }
     vec![
         format!("  store ptr {}, ptr {}", state_reg, state_slot),
         format!(

crates/perry-codegen/src/inprocess.rs

@@ -131,6 +131,10 @@ fn global_init(mllvm: &[String]) {
         let cfg = InitializationConfig::default();
         Target::initialize_aarch64(&cfg);
         Target::initialize_x86(&cfg);
+        // Standalone WASI (#11375): only with the off-by-default `target-wasi`
+        // feature, so the shipped compiler does not carry the backend.
+        #[cfg(feature = "target-wasi")]
+        Target::initialize_webassembly(&cfg);
         if !mllvm.is_empty() {
             let mut argv: Vec<CString> = vec![CString::new("perry-llvm-inprocess").unwrap()];
             for flag in mllvm {

crates/perry-codegen/src/lib.rs

@@ -80,6 +80,8 @@ pub mod typed_feedback_profile;
 pub(crate) mod typed_shape;
 pub mod types;
 pub mod unit_cache;
+#[cfg(feature = "target-wasi")]
+mod wasm32;
 
 pub use codegen::{
     compile_module, context_free_ctor_abi, context_free_ctor_param_count,

crates/perry-codegen/src/lower_call/new_alloc.rs

@@ -545,7 +545,12 @@ fn emit_instance_alloc_inner(
             field_count,
         ) && image_size_agrees)
             || wide_birth_image;
-        if !descriptor_facts_exact || (!force_inline_new && !new_site_is_in_loop(ctx)) {
+        // ILP32 (wasm32 WASI, #11378): the inline bump below reads
+        // `InlineArenaState` at LP64 offsets; take the outlined call.
+        if !descriptor_facts_exact
+            || (!force_inline_new && !new_site_is_in_loop(ctx))
+            || crate::codegen::helpers::ilp32_target()
+        {
             let keys_slot = if let Some(s) = ctx.class_keys_slots.get(class_name).cloned() {
                 s
             } else {

crates/perry-codegen/src/target_layout.rs

@@ -62,6 +62,12 @@ pub fn target_is_ilp32(target_triple: &str) -> bool {
 /// makes those target-derived. The only ILP32 triple the driver produces is
 /// watchOS `arm64_32`, which is opt-in (`PERRY_WATCHOS_ARM64_32`).
 pub fn ilp32_codegen_refusal(target_triple: &str) -> Option<String> {
+    // The one ILP32 target with a real lowering: wasm32 WASI, behind the
+    // off-by-default `target-wasi` feature (runtime ABI adapters in
+    // `crate::wasm32`, ILP32 shadow-stack/inline-path layouts).
+    if wasm32_lowering(target_triple) {
+        return None;
+    }
     target_is_ilp32(target_triple).then(|| {
         format!(
             "target `{target_triple}` has 32-bit pointers, and Perry's LLVM backend \
@@ -72,6 +78,15 @@ pub fn ilp32_codegen_refusal(target_triple: &str) -> Option<String> {
     })
 }
 
+/// True when this compile targets wasm32 WASI AND the compiler was built with
+/// the `target-wasi` feature — the only condition under which any wasm32
+/// lowering runs. Always false in a default build.
+pub fn wasm32_lowering(target_triple: &str) -> bool {
+    cfg!(feature = "target-wasi")
+        && target_triple.starts_with("wasm32")
+        && target_triple.contains("wasi")
+}
+
 /// Exclusive upper bound accepted by the runtime's `is_valid_obj_ptr` for a
 /// candidate GC address. Linux-family AArch64 can use the full low 48-bit VA
 /// range; every other target keeps the canonical low-half 47-bit ceiling.
@@ -326,7 +341,7 @@ mod tests {
     fn ilp32_targets_are_refused_and_lp64_targets_are_not() {
         for triple in [
             "arm64_32-apple-watchos",
-            "wasm32-wasip2",
+            "wasm32-unknown-unknown",
             "i686-unknown-linux-gnu",
             // Not named anywhere: refused because they are not known 64-bit.
             "i586-unknown-linux-gnu",
@@ -347,6 +362,55 @@ mod tests {
         ] {
             assert_eq!(ilp32_codegen_refusal(triple), None, "{triple}");
         }
+        // wasm32 WASI has a real lowering, but only in a `target-wasi` build.
+        assert_eq!(
+            ilp32_codegen_refusal("wasm32-unknown-wasip2").is_none(),
+            cfg!(feature = "target-wasi"),
+            "wasm32 WASI is refused exactly when the feature is off"
+        );
+    }
+
+    #[test]
+    fn wasm32_lowering_needs_the_feature_and_a_wasi_triple() {
+        assert_eq!(
+            wasm32_lowering("wasm32-unknown-wasip2"),
+            cfg!(feature = "target-wasi")
+        );
+        assert_eq!(
+            wasm32_lowering("wasm32-wasip1"),
+            cfg!(feature = "target-wasi")
+        );
+        // Browser wasm has its own backend and never reaches this one.
+        assert!(!wasm32_lowering("wasm32-unknown-unknown"));
+        assert!(!wasm32_lowering("x86_64-unknown-linux-gnu"));
+        assert!(!wasm32_lowering("arm64_32-apple-watchos"));
+    }
+
+    /// With the feature, a wasm32 WASI module compiles end to end and its
+    /// runtime calls come out adapted (the i64-handle call below would be a
+    /// link-time signature mismatch without the pass).
+    #[cfg(feature = "target-wasi")]
+    #[test]
+    fn compile_module_lowers_a_wasm32_wasi_module() {
+        let module = perry_hir::Module::new("wasi_smoke");
+        let opts = crate::CompileOptions {
+            target: Some("wasm32-unknown-wasip2".into()),
+            emit_ir_only: true,
+            is_entry_module: true,
+            output_type: "executable".into(),
+            ..Default::default()
+        };
+        let ir = String::from_utf8(crate::compile_module(&module, opts).expect("wasm32 compiles"))
+            .expect("IR is UTF-8");
+        assert!(
+            ir.contains("target triple = \"wasm32-unknown-wasip2\""),
+            "{ir}"
+        );
+        // Every runtime declaration is the runtime's real signature.
+        assert!(
+            ir.contains("declare ptr @js_string_from_bytes(ptr, i32)"),
+            "{ir}"
+        );
     }
 
     /// The refusal must be reached by the real entry point, not just exist.