Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR 0013 — WASI 0.2 Component Model for rlg-wasm (Phase 22: scaffold)

  • Status: Accepted
  • Date: 2026-07-05
  • Phase: 22 (per docs/IMPLEMENTATION-PLAN-v0.1.0.md)
  • Deciders: repository maintainers
  • Related: ADR 0010, 0011, 0012 — same scaffold-then-fill pattern.

Context

WASI 0.2 preview 2 (component model) reached mainstream tooling availability in 2025–2026. Wasmtime, jco, and Fermyon’s Spin all accept components as their primary distribution artefact. Enterprise WASM adopters increasingly expect components, not wasm-bindgen-flavoured cdylibs.

The plan called for rlg-wasm to expose a wasi:logging-shaped WIT interface consumable by any WASI 0.2 host.

Decision

Phase 22 lands the WIT interface definition + docs + ADR. The wit-bindgen-driven Rust codegen and the wasm32-wasip2 build target land in Phase 22.1. Same scaffold-then-fill pattern as Phase 19c (gRPC), 20 (io_uring), 21 (eBPF).

Delivered (Phase 22)

  • crates/rlg-wasm/wit/rlg.wit — component interface at rlg:[email protected], world rlg-logger, exporting the logger interface with info / warn / error / debug methods. Mirrors the existing JavaScript ABI so both paths present the same shape.
  • README section documenting the WIT and the intended host invocation (wasmtime run --component).
  • ADR 0013 (this document) — trade-offs, alternatives, gate for Phase 22.1.

Deferred (Phase 22.1)

  • wit-bindgen dependency + build-script integration.
  • #[cfg(target_arch = "wasm32", target_env = "p2")]-gated Rust glue that impls the exported logger interface via the existing RlgWasm type.
  • wasmtime-based CI smoke test that runs wasmtime run --component out.wasm and asserts the exported functions can be called.
  • New examples/wasi_component.rs demonstrating the component build.

Why not full delivery in one commit

  • wit-bindgen 0.34+ is required for WASI 0.2 preview 2 support. Older versions produce components that Wasmtime rejects.
  • The wasm32-wasip2 target is nightly-only in some rustc channels (stable landed in 1.85, released Q1 2025). Existing workspace MSRV is 1.88.
  • The CI matrix needs a wasmtime install step and a component smoke test, both non-trivial.

Landing the WIT alone is safer, immediately useful (consumers can inspect the interface), and keeps CI green.

What the WIT commits us to

Every function in the WIT is now a public API surface. Any future change to signature (arg types, arg count, return type) is a breaking change subject to semver-checks.

Adding new methods is additive-safe. Adding new interfaces is additive-safe. Removing anything is breaking.

Alternatives considered

  • Skip WASI 0.2 entirely. Rejected — enterprise WASM deployments moved to components in 2025–2026; not supporting the component model foreclos on that segment.
  • Use wasi:logging verbatim instead of defining our own interface. wasi:logging (WASI Preview 2) has a stable log(level, context, message) shape. Our interface adds structured attributes (attributes-json), which is what rlg’s value proposition demands. We’ll accept wasi:logging as an input interface in Phase 22.2 for consumers who prefer the standard-first shape.
  • Full delivery in one commit. Rejected on CI-risk grounds: wasmtime install + component compile + smoke test have not been shaken out in this workspace’s CI environment. Ship WIT now, iterate on tooling in Phase 22.1.

References