Adopt Component Model fixed-length lists (🔧) for the next WASI 0.3.x release

[ricochet]

This issue proposes that WASI adopt the Component Model's fixed-length list feature (gated as 🔧 in the Component Model's gated features), following the process described in CONTRIBUTING.md § Adopting Component Model features.

Feature

The 🔧 gate covers the optional length immediate on the list type constructor: list<T, N> (WIT.md § Types, Explainer § Type Definitions). A fixed-length list has the low-level memory representation of a homogeneous tuple of the same length. The elements are stored inline, with no pointer/length indirection while keeping the dynamic indexing and source-level bindings of a list. The length must be greater than 0.

get-ipv4-address: func() -> list<u8, 4>;

This gives interfaces a natural way to express fixed-size data like addresses, digests, coordinates, matrices. Today these must be spelled as wide tuples (e.g. tuple<u16, u16, u16, u16, u16, u16, u16, u16> for an IPv6 address) or as dynamically-sized list<u8> with out-of-band length invariants.

Unlike some WIT-level features, fixed-length lists specialize the canonical ABI representation, so adopting 🔧 requires support in runtimes and bindings generators, not just WIT tooling.

Stability

• The feature's design is complete and merged into the Component Model specification: Add optional fixed length to lists component-model#384 (merged 2024-09-19), with the non-empty-length requirement documented in Document fixed-size-lists must be non-empty component-model#504 (merged 2025-04-25).
• It is tracked in the Explainer's gated features list as 🔧.
• No further breaking changes are expected.

Iteration and feedback

This feature was designed nearly two years between the spec merge and this proposal with design refinements driven by implementation feedback throughout:

• Spec: fixed length added to list in Add optional fixed length to lists component-model#384 (2024-09); the non-empty requirement was clarified from implementation feedback in Document fixed-size-lists must be non-empty component-model#504 (2025-04).
• wasm-tools: fixed-length list support in Fixed length list support bytecodealliance/wasm-tools#1992 (merged 2025-04-28); terminology unified to "fixed-length lists" in rename fixed size list to fixed-length lists bytecodealliance/wasm-tools#2421 (2026-06-14); a defensive element-count limit added in Limit the element count of fixed-length lists bytecodealliance/wasm-tools#2537 (2026-06-16).
• Wasmtime: host-side support (typed Val representation, canonical ABI lifting/lowering) in Fixed-length lists, host side bytecodealliance/wasmtime#12315 (merged 2026-07-07).
• Support in JCO feat(transpile): Support fixed length lists bytecodealliance/jco#1315 (merged 2026-03-18)
• wit-bindgen support for Rust and Moonbit is solid but other languages need support added.

wit-bindgen-core defines dedicated ABI instructions FixedLengthListLift/FixedLengthListLower/FixedLengthListLowerToMemory/ FixedLengthListLiftFromMemory (crates/core/src/abi.rs:337-361) and dispatches type declarations via TypeDefKind::FixedLengthList(t, size) (crates/core/src/lib.rs:205,245).

WASI APIs that would depend on it

Fixed-size data appears throughout WASI's API surface, and proposals in the pipeline would use list<T, N> in newly added or newly stabilized APIs:

• wasi-sockets — IP addresses, today spelled as wide tuples
  (tuple<u8, u8, u8, u8> for IPv4, tuple<u16, ...> ×8 for IPv6)
• [wasi-webgpu] — vectors and matrices
• Embedded-focused proposals (wasi-i2c, wasi-spi, wasi-usb) — fixed-size registers and buffers

Adopting 🔧 does not change any already-released wasi:* API: existing stable signatures keep their current types. It makes list<T, N> available to stable (@since-gated) APIs from the adopting release onward, and part of the baseline that runtimes and toolchains must support for that release.

Requested action

Per CONTRIBUTING.md § Adopting Component Model features, we believe the stability criteria are met: the design is complete, and the feature has been through an extended phase of iteration and feedback across the spec, WIT tooling, and runtime implementations.

We therefore aim to add a vote to an upcoming WASI Subgroup meeting agenda to adopt Component Model fixed-length lists (🔧) for inclusion in the next WASI 0.3.x release. Once adopted:

• Stable (@since-gated) WASI APIs in the next release may depend on the feature.
• The release notes for that version call out the newly adopted Component Model feature.
• From that release onward, 🔧 is part of the baseline set of Component Model features required to implement that WASI version.

[lukewagner]

Coincidentally, there has just been some recent design discussion in CM/#640 about bounded lists (which would be a separate feature to complement/extend fixed-length lists 🔧) that suggests that maybe we should change the ABI flattening rules for bounded- and fixed-length lists. Until those bottom out, it's probably a good idea to hold off on releasing fixed-length lists. (cc @cpetig and @Felix-El)

[alexcrichton]

Another aspect from Wasmtime's side at least as well is that fixed-length-lists aren't integrated into fuzzing right now, so this isn't something we'd want to turn on by default just yet in Wasmtime. That wouldn't necessarily block this, but it would mean that it'd still be gated in Wasmtime until fuzzing is implemented

[cpetig]

To explain why it came to this situation:

• fixed-length lists were initially modeled to behave like tuples, so the elements get individually flattened as values. This avoided introducing a whole new concept and simply accepted that flattened lists need to be stored to memory before they can be indexed or iterated over.
• This compromise is much less appealing for bounded lists, where some arguments are simply not needed but need to be passed on the value stack. In addition this feels wasteful for passing a few bounded lists as the flat arguments quickly run out. Flattening them as (pointer+length) makes them more like normal lists.
• This only applies to (a small number of) arguments, return values never fit into the single value slot available.
• Felix pointed out that a new separation of a fixed number of list values into the argument or return area would solve both drawbacks. So at the complexity cost of passing some values in an argument area and some in the flat value stack, these lists get indexable, iterable and only valid values need to be loaded from memory.
• With implementing this more reasonable model for bounded lists, fixed-length lists should flatten in the same way - fixing the previously introduced limitations while still being caller allocated in linear memory.
• (I just realized) A lot of the complex flattening logic of fixed-length lists becomes trivial with this change, this was the single most complicated part of the implementation. Several DoS doubts arose from this.

We promise to implement the new scheme within a few days, the only question is whether this change should require a lifting option to indicate the new flattening rule to all tools - or whether we accept a silent breaking of existing tools (I can't tell off-hand whether using an old linker/wac/wasm-tools will affect correctness here or if only wit-bindgen is affected on both sides, if wasm-tools and wasm-linker need an updated wasm-tools I would propose a loud failure, likewise if wasmtime would do anything but trap when executing old components). And if we go for the lifting option whether supporting both variants in wasmtime is necessary. I guess I should start investigating.

[cpetig]

We found that the number of core parameters changes across this ABI incompatibility (unless you use a list<u32,1> for argument or result, which is highly unlikely). So incompatible wasm binaries should simply not validate across this change.

[ricochet]

Ok then it sounds like the design and stability requirement for this feature has not yet been met. My preference is to close this issue and once ready, open a bounded-list issue that will encompass both. Sound ok @lukewagner ?

[cpetig]

I guess more than my ABI plans @alexcrichton's latest findings support that this isn't yet ready for WASI, see the TODO entries in Implement WIT Fixed-Length-Lists .