feat: Multi-Bundle Support for WASI Preview2/Preview3 Coexistence

[avrabe]

Summary

Enable multiple toolchain bundles in the same workspace, allowing components targeting different WASI versions (e.g., Preview2 and Preview3) to coexist and build together.

Current State

• Single global bundle selection via wasm_component_bundle.configure(bundle = "stable-2025-12")
• All toolchain repositories are singletons (@wasm_tools_toolchains, @wasmtime_toolchain, etc.)
• Cannot have different components use different tool versions in the same build

Use Case

# User wants BOTH in the same workspace:
rust_wasm_component(
    name = "legacy_component",
    wasi_version = "preview2",  # Uses wasm-tools 1.243.0, wasmtime 39.0.1
    srcs = ["legacy.rs"],
)

rust_wasm_component(
    name = "new_component", 
    wasi_version = "preview3",  # Uses wasm-tools 2.0.0, wasmtime 40.0.0
    srcs = ["modern.rs"],
)

# Both build in same `bazel build` invocation

Proposed Architecture

Layer 1: Constraint Definitions

# //platforms/BUILD.bazel
constraint_setting(
    name = "wasi_version",
    default_constraint_value = ":preview2",
)

constraint_value(name = "preview2", constraint_setting = ":wasi_version")
constraint_value(name = "preview3", constraint_setting = ":wasi_version")

Layer 2: Named Bundle Instances

# MODULE.bazel
wasm_bundle.configure(name = "preview2", bundle = "stable-2025-12")
wasm_bundle.configure(name = "preview3", bundle = "experimental-preview3")

# Creates separate repositories:
# @wasm_tools_preview2, @wasmtime_preview2, ...
# @wasm_tools_preview3, @wasmtime_preview3, ...

Layer 3: Constraint-Based Toolchain Registration

Each bundle's toolchain registered with target_compatible_with:

# Generated in @wasm_tools_preview2//:BUILD.bazel
toolchain(
    name = "wasm_tools_toolchain",
    target_compatible_with = ["@rules_wasm_component//platforms:preview2"],
    toolchain = ":wasm_tools_toolchain_impl",
    toolchain_type = "@rules_wasm_component//toolchains:wasm_tools_toolchain_type",
)

Layer 4: Rule Transitions

Rules get wasi_version attribute that triggers configuration transition:

rust_wasm_component = rule(
    attrs = {
        "wasi_version": attr.string(default = "preview2", values = ["preview2", "preview3"]),
    },
    cfg = wasi_version_transition,  # Transition sets //platforms:wasi_version
    toolchains = ["//toolchains:wasm_tools_toolchain_type"],
)

Architecture Diagram

MODULE.bazel
    │ wasm_bundle.configure(name = "preview2", bundle = "stable-2025-12")
    │ wasm_bundle.configure(name = "preview3", bundle = "experimental-p3")
    ▼
┌─────────────────────────────────────────────────────────────────┐
│                    CONSTRAINT DEFINITIONS                        │
│  constraint_setting(name = "wasi_version")                       │
│  constraint_value(name = "preview2")                             │
│  constraint_value(name = "preview3")                             │
└─────────────────────────────────────────────────────────────────┘
          │                                     │
          ▼                                     ▼
┌─────────────────────┐             ┌─────────────────────┐
│ @wasm_tools_preview2│             │ @wasm_tools_preview3│
│ wasm-tools 1.243.0  │             │ wasm-tools 2.0.0    │
│ target_compatible   │             │ target_compatible   │
│ = [":preview2"]     │             │ = [":preview3"]     │
└─────────────────────┘             └─────────────────────┘
          │                                     │
          └─────────────┬───────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────────────┐
│  BUILD.bazel                                                     │
│  rust_wasm_component(name = "p2", wasi_version = "preview2")    │
│  rust_wasm_component(name = "p3", wasi_version = "preview3")    │
│  # Bazel toolchain resolution picks correct version!             │
└─────────────────────────────────────────────────────────────────┘

Implementation Tasks

• Create //platforms/BUILD.bazel with constraint_setting and constraint_values
• Update wasm/extensions.bzl to support named bundle instances
• Modify toolchain repository rules to accept bundle name suffix
• Update generated BUILD files to include target_compatible_with
• Add wasi_version attribute to all component rules (rust, cpp, go, js)
• Implement configuration transitions for WASI version selection
• Update register_toolchains() to register all bundle variants
• Add tests for multi-bundle builds
• Documentation for multi-WASI-version workflows

Files to Modify

File	Change
platforms/BUILD.bazel	New: constraint definitions
wasm/extensions.bzl	Named bundle instances
toolchains/*_toolchain.bzl	Add target_compatible_with to generated BUILD
rust/defs.bzl	Add wasi_version attr + transition
cpp/defs.bzl	Add wasi_version attr + transition
go/defs.bzl	Add wasi_version attr + transition
js/defs.bzl	Add wasi_version attr + transition

Benefits

• Same BUILD file can have preview2 and preview3 components
• Bazel's toolchain resolution handles version selection automatically
• Works with caching - different configurations cached separately
• Future-proof for preview4, etc.
• Enables gradual migration between WASI versions

Impact

• Effort: Medium-High (~15-20 hours)
• Risk: Medium (touches all component rules)
• Value: High (enables WASI version migration paths)

Related

• Builds on: feat: Toolchain Version Bundles for Guaranteed Compatibility #254 (Toolchain Version Bundles)
• Enables: Smooth Preview2 → Preview3 migration

[avrabe]

⏸️ Status: Future - Not needed until WASI P3 stabilizes

Multi-bundle support is a nice-to-have for future WASI Preview 2 → Preview 3 migration scenarios.

Current status:

• Single bundle support works well for current WASI P2 ecosystem
• Toolchain version bundles are implemented and guaranteed compatible
• No immediate need for multiple bundles

When this becomes relevant:

• WASI Preview 3 stabilizes
• Users need to support both P2 and P3 workloads
• Migration period requires side-by-side versions

Will revisit when P3 stabilizes. Tracked in strategic plan.

[avrabe]

Architecture Analysis (2026-03-22)

Partially addressed by today's P3 work. Current state:

• ✅ stable-2026-03 (P2) and experimental-p3 bundles exist
• ✅ Per-target wasi_version = "p2" | "p3" attribute on Rust and Python rules
• ✅ Same tools serve both — wasi_version is a target property, not toolchain property
• ✅ P3 WIT deps available via wasi_wit.init(include_p3 = True)
• ✅ CI tests both P2 and P3 builds

What's NOT needed (original concern resolved):
The issue assumed P2/P3 would need different tool versions. In practice, wasmtime 43+ and wit-bindgen 0.54+ handle both P2 and P3. No version conflict.

What remains:

• Bundle validation: fail at analysis time if a target requests wasi_version = "p3" but the active bundle doesn't support it
• When P3 stabilizes: users may want to pin P2 components to older proven versions while using latest for P3

Depends on: #250 (meta-toolchain) makes bundle selection the natural place for this validation.

STPA alignment: SC-004 (track explicit P3 RC tags) is implemented. Bundle wasi_rc field tracks the RC version.

Full analysis: docs/superpowers/plans/2026-03-22-unified-architecture-analysis.md

[avrabe]

Closing — P2/P3 coexistence delivered via target-level wasi_version

PRs #409, #410, #416 shipped:

• Per-target wasi_version = "p2" | "p3" on all 7 language rules
• stable-2026-03 (P2) and experimental-p3 bundles
• P3 WIT deps from WASI monorepo RC
• CI tests both P2 and P3 builds

Same tools serve both versions — no multi-bundle version conflicts needed.