Adopt Component Model map type (🗺️) for the next WASI 0.3.x release

[ricochet]

This issue proposes that WASI adopt the Component Model's map type (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 map<K, V> WIT type (WIT.md § Types). A map is semantically equivalent to a list of key–value pairs — it shares the same canonical ABI representation as list<tuple<K, V>> — but is intended to be represented by bindings generators as the source language's native mapping type (associative array, hash table, dictionary), with last-key-wins semantics for duplicate keys. Key types are restricted to bool, integers, char, and string.

interface config {
  get-all: func() -> map<string, string>;
}

Because the ABI representation is unchanged from list<tuple<K, V>>, the feature is primarily a WIT-level and bindings-level improvement: it lets interfaces state intent (this is a keyed collection) and gives component authors idiomatic bindings without any new runtime machinery.

Stability

• The feature's design is complete and merged into the Component Model specification: Add a 'map<K,V>' type component-model#554 (merged 2026-05-12).
• It is tracked in the Explainer's gated features list as 🗺️.
• No further breaking changes are expected.

Iteration and feedback

Implementation experience preceded the spec merge by several months, and the feedback it produced was incorporated into the final design:

• wasm-tools: map type support in feat(wit): add map type support bytecodealliance/wasm-tools#2356 (merged 2025-12-22, roughly five months before the spec PR merged); compatibility feedback incorporated in Escape map when printing WITs bytecodealliance/wasm-tools#2424 (escaping map when printing WITs, so existing packages using map as an identifier keep round-tripping).
• The key-type restriction (bool, integers, char, string) and the duplicate-key (last-key-wins) semantics were settled through review on the spec and implementation PRs.
• JCO: feat(bindgen): add maps support bytecodealliance/jco#1757
• Runtimes pick up support through their WIT tooling (e.g. Wasmtime via its wasm-tools dependency), since no canonical ABI changes are involved.
• This means the majority of integration is for guest language toolchains and language bindings generators. The most commonly used is wit-bindgen.

wit-bindgen-core (crates/core) has full ABI support with dedicated MapLower/MapLift/IterMapKey/IterMapValue/GuestDeallocateMap instructions in abi.rs, lowered with the same linear-memory layout as list<tuple<K, V>>.

Per-language status in wit-bindgen

Language	Codegen	Runtime round-trip test	Landed
Rust	✅ (configurable map_type, e.g. std::collections::HashMap)	✅	#1562 (core PR itself touched Rust)
Go	✅	✅	#1583
MoonBit	✅	✅	#1584
C	✅	✅	#1611
C#	✅	⏳ draft PR open	#1603 (codegen), #1640 (runtime tests, open/draft)
C++	✅	❌ none yet	#1590
Markdown (docs gen)	✅ (type rendering only)	n/a	#1562

Relevant PRs (all by Yordis unless noted)

• #1562 — "Add map support" (merged 2026-04-09) — foundational: core ABI +
  Rust/C/C++/C#/Go/MoonBit/Markdown scaffolding, plus tests/codegen/map.wit
  and tests/runtime/map/*
• #1583 — feat(go): add map type support (merged 2026-04-10)
• #1584 — feat(moonbit): add map type support (merged 2026-04-14)
• #1603 — feat(csharp): add map type support (merged 2026-05-05)
• #1611 — feat(c): add map type support (merged 2026-06-02)
• #1590 — feat(cpp): add map type support (merged 2026-06-29)
• #1640 — test(csharp): cover map runtime exports (open, draft) —
  closes the gap where C# map support is only exercised by generated-bindings
  inspection, not actual runtime composition/roundtrip

WASI APIs that would depend on it

Several WASI proposals model keyed collections today as list<tuple<string, T>> and would use map in newly added or newly stabilized APIs:

• wasi-config: configuration lookups such as get-all
• wasi-keyvalue: batch operations over keys and values
• wasi-otel: attribute sets on spans, metrics, and logs

Adopting 🗺️ does not change any already-released wasi:* API: existing stable signatures keep their current types. It makes map 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 a phase of iteration and feedback across the toolchain implementations that consume WIT.

We therefore aim to add a vote to an upcoming WASI Subgroup meeting agenda to adopt the Component Model map type (🗺️) 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.

[yordis]

@ricochet trying to get bytecodealliance/wit-bindgen#1667 to work