Add map support (#1562)

* feat: add map support across backends

Implement map type rendering plus lowering/lifting/deallocation support across the C, C++, C#, Go, MoonBit, and Markdown backends, and add map codegen/runtime tests.

This aligns non-Rust generators with core map ABI support and fixes the Go test harness module replacement path needed for map codegen verification.

Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>

* revert: remove map support from non-Rust backends

Defer map codegen for MoonBit, Go, C#, C++, and C to future PRs
that include runtime tests and review from language-specific
maintainers. Only todo!() stubs for the new MapLower/MapLift/
IterMapKey/IterMapValue/GuestDeallocateMap instruction variants
are kept so exhaustive matches compile.

* revert: drop unrelated go.mod replace path fix

This change was a fix for a latent bug from the vanity imports migration
but is unrelated to map support. Removing to keep the PR focused on Rust.

* refactor: clean up map type support across backends

- Make `InterfaceGenerator::type_map` a required trait method instead of
  providing a default `todo!()` impl, so missing implementations are
  caught at compile time rather than runtime.
- Remove `RuntimeItem::MapType` indirection in the Rust backend; reference
  `{rt}::Map` directly instead of emitting a `pub use` re-export.
- Fix borrowed map rendering to use `&Map<K, V>` instead of the
  incorrect `&[(K, V)]` slice syntax that was copy-pasted from lists.
- Add explanatory comments on map ABI methods that reuse list
  read/write helpers (maps share the list<tuple<K, V>> memory layout).
- Add explicit `type_map` todo stubs to C, C++, C#, Go, and MoonBit
  backends.

* Address PR review: make anonymous_type_map required and fix runner test

- Make `anonymous_type_map` a required method on `AnonymousTypeGenerator`
  trait (no default impl), consistent with all other methods in the trait.
- Add explicit `anonymous_type_map` todo!() implementation to C backend.
- Fix map runner test to construct proper Map types instead of passing
  slice literals, matching the generated `&Map<K, V>` parameter signatures.

* Mark map.wit codegen test as expected failure for unsupported backends

The map.wit codegen test hits todo!() panics in backends that don't yet
implement map support (C, C++, C#, Go, MoonBit). Add map.wit to each
backend's should_fail_verify so CI treats these as expected failures.

* Fix rustfmt and use starts_with for C map.wit codegen variants

- Run cargo fmt to fix formatting in c/lib.rs, test/c.rs, test/moonbit.rs.
- Use starts_with("map.wit") for the C backend's should_fail_verify to
  catch all codegen test variants (no-sig-flattening, autodrop, async).

* Add comment back

Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>

* Expand map test coverage with additional runtime and codegen tests

Add runtime tests for empty maps, option values, maps inside records,
inline anonymous map types, and a 100-entry stress test. Expand codegen
tests with option values, nested maps, record values, bool keys, and
char keys.

* Add map tests for nested maps, multi-param, variant, and result types

Exercise additional ABI code paths: nested map<K, map<K2, V>> with
recursive lower/lift blocks, multiple map parameters with independent
ptr/len pairs, map as a variant arm payload, map inside result<ok, err>,
and tuple-with-map in codegen.

* Add tuple-with-map and single-entry map runtime tests

Exercise map inside an anonymous tuple (filter_mode_preserve_top path)
and the single-entry boundary case.

* Add WitMap trait and configurable map_type for Rust bindings

Instead of hardcoding HashMap/BTreeMap, introduce a WitMap trait that
generated code delegates to for map construction, insertion, and length.
This lets users swap in their own map type via the new `map_type`
bindgen option. The default is BTreeMap (always, regardless of std).

* Format code
Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>

* Add tests for WitMap trait and map_type codegen option

- Unit tests for WitMap trait impls (BTreeMap, HashMap, reference blanket)
- Proc-macro integration tests exercising map_type with HashMap and default
- Codegen test variant running all .wit files with --map-type=HashMap

* Fix &&BTreeMap WitMap trait resolution for borrowed map variants

Remove `type Iter` and `wit_map_into_iter` from the `WitMap` trait and
drop the `IntoIterator` bound from the blanket `&T` impl. This allows
the blanket impl to apply at any reference depth (e.g. `&&BTreeMap`)
which is needed when codegen emits `WitMap::wit_map_len(&map)` on an
already-borrowed map.

Generated lowering code now uses `IntoIterator::into_iter(map)` for
iteration, which the standard library already provides for both owned
and borrowed map types.

* Fix map codegen for borrowed ownership mode

Use method syntax (.wit_map_len() and .into_iter()) in generated
MapLower code instead of UFCS. This lets Rust's auto-deref handle
&&BTreeMap operands that arise when the borrow-mode param wrapper
adds an extra & prefix to already-borrowed map arguments.

A scoped `use WitMap;` import is emitted so method resolution finds
the trait's wit_map_len method.

* Use .len() and .into_iter() in MapLower codegen

Revert MapLower to use method syntax for length and iteration, matching
the original pre-WitMap code. Method syntax auto-derefs through &&Map
operands that arise in borrowed ownership modes.

Simplify WitMap trait to just new/push (used only in MapLift). The map
type must also provide .len() and implement IntoIterator, which all
standard map types already do.

* Route MapLower .len() through WitMap trait via module-level import

Instead of calling .len() directly (which bypasses the WitMap trait and
would break custom map types), generated code now calls .wit_map_len()
using method syntax. The WitMap trait is brought into scope via a
module-level `use _rt::WitMap;` import, avoiding the scoping issues
that arose from emitting `use` inside nested blocks.

* Format code

---------

Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>

Author: yordis

crates/c/src/lib.rs

@@ -1746,6 +1746,10 @@ void __wasm_export_{ns}_{snake}_dtor({ns}_{snake}_t* arg) {{
         todo!("named fixed-length list types are not yet supported in the C backend")
     }
 
+    fn type_map(&mut self, _id: TypeId, _name: &str, _key: &Type, _value: &Type, _docs: &Docs) {
+        todo!("map types are not yet supported in the C backend")
+    }
+
     fn type_future(&mut self, id: TypeId, _name: &str, _ty: &Option<Type>, docs: &Docs) {
         self.src.h_defs("\n");
         self.docs(docs, SourceType::HDefs);
@@ -1867,6 +1871,10 @@ impl<'a> wit_bindgen_core::AnonymousTypeGenerator<'a> for InterfaceGenerator<'a>
     ) {
         todo!("print_anonymous_type for fixed length list");
     }
+
+    fn anonymous_type_map(&mut self, _id: TypeId, _key: &Type, _value: &Type, _docs: &Docs) {
+        todo!("anonymous map types are not yet supported in the C backend");
+    }
 }
 
 pub enum CTypeNameInfo<'a> {

crates/core/src/abi.rs

@@ -310,6 +310,28 @@ def_instruction! {
             ty: TypeId,
         } : [2] => [1],
 
+        /// Lowers a map into a canonical pointer/length pair.
+        ///
+        /// This operation pops a map value from the stack and pushes pointer
+        /// and length. A block is popped from the block stack to lower one
+        /// key/value entry into linear memory.
+        MapLower {
+            key: &'a Type,
+            value: &'a Type,
+            realloc: Option<&'a str>,
+        } : [1] => [2],
+
+        /// Lifts a canonical pointer/length pair into a map.
+        ///
+        /// This operation consumes pointer and length from the stack. A block
+        /// is popped from the block stack and must produce key/value for one
+        /// map entry.
+        MapLift {
+            key: &'a Type,
+            value: &'a Type,
+            ty: TypeId,
+        } : [2] => [1],
+
         /// Pops all fields for a fixed list off the stack and then composes them
         /// into an array.
         FixedLengthListLift {
@@ -349,6 +371,14 @@ def_instruction! {
         /// This is only used inside of blocks related to lowering lists.
         IterElem { element: &'a Type } : [0] => [1],
 
+        /// Pushes an operand onto the stack representing the current map key
+        /// for each map iteration.
+        IterMapKey { key: &'a Type } : [0] => [1],
+
+        /// Pushes an operand onto the stack representing the current map value
+        /// for each map iteration.
+        IterMapValue { value: &'a Type } : [0] => [1],
+
         /// Pushes an operand onto the stack representing the base pointer of
         /// the next element in a list.
         ///
@@ -581,6 +611,17 @@ def_instruction! {
             element: &'a Type,
         } : [2] => [0],
 
+        /// Used exclusively for guest-code generation this indicates that a
+        /// map is being deallocated. The ptr/length are on the stack and are
+        /// popped off and used to deallocate the map entry buffer.
+        ///
+        /// This variant also pops a block off the block stack to be used as
+        /// the body of the deallocation loop over map entries.
+        GuestDeallocateMap {
+            key: &'a Type,
+            value: &'a Type,
+        } : [2] => [0],
+
         /// Used exclusively for guest-code generation this indicates that
         /// a variant is being deallocated. The integer discriminant is popped
         /// off the stack as well as `blocks` number of blocks popped from the
@@ -875,7 +916,7 @@ fn needs_deallocate(resolve: &Resolve, ty: &Type, what: Deallocate) -> bool {
             TypeDefKind::Future(_) | TypeDefKind::Stream(_) => what.handles(),
             TypeDefKind::Unknown => unreachable!(),
             TypeDefKind::FixedLengthList(t, _) => needs_deallocate(resolve, t, what),
-            TypeDefKind::Map(..) => todo!(),
+            TypeDefKind::Map(_, _) => true,
         },
 
         Type::Bool
@@ -1618,7 +1659,25 @@ impl<'a, B: Bindgen> Generator<'a, B> {
                         self.lower(ty);
                     }
                 }
-                TypeDefKind::Map(..) => todo!(),
+                TypeDefKind::Map(key, value) => {
+                    let realloc = self.list_realloc();
+                    let value_offset = self.bindgen.sizes().field_offsets([key, value])[1].0;
+                    self.push_block();
+                    self.emit(&IterMapKey { key });
+                    self.emit(&IterBasePointer);
+                    let key_addr = self.stack.pop().unwrap();
+                    self.write_to_memory(key, key_addr, Default::default());
+                    self.emit(&IterMapValue { value });
+                    self.emit(&IterBasePointer);
+                    let value_addr = self.stack.pop().unwrap();
+                    self.write_to_memory(value, value_addr, value_offset);
+                    self.finish_block(0);
+                    self.emit(&MapLower {
+                        key,
+                        value,
+                        realloc,
+                    });
+                }
             },
         }
     }
@@ -1819,7 +1878,16 @@ impl<'a, B: Bindgen> Generator<'a, B> {
                         id,
                     });
                 }
-                TypeDefKind::Map(..) => todo!(),
+                TypeDefKind::Map(key, value) => {
+                    let value_offset = self.bindgen.sizes().field_offsets([key, value])[1].0;
+                    self.push_block();
+                    self.emit(&IterBasePointer);
+                    let entry_addr = self.stack.pop().unwrap();
+                    self.read_from_memory(key, entry_addr.clone(), Default::default());
+                    self.read_from_memory(value, entry_addr, value_offset);
+                    self.finish_block(2);
+                    self.emit(&MapLift { key, value, ty: id });
+                }
             },
         }
     }
@@ -1907,6 +1975,8 @@ impl<'a, B: Bindgen> Generator<'a, B> {
             Type::Id(id) => match &self.resolve.types[id].kind {
                 TypeDefKind::Type(t) => self.write_to_memory(t, addr, offset),
                 TypeDefKind::List(_) => self.write_list_to_memory(ty, addr, offset),
+                // Maps have the same linear memory layout as list<tuple<K, V>>.
+                TypeDefKind::Map(_, _) => self.write_list_to_memory(ty, addr, offset),
 
                 TypeDefKind::Future(_) | TypeDefKind::Stream(_) | TypeDefKind::Handle(_) => {
                     self.lower_and_emit(ty, addr, &I32Store { offset })
@@ -2016,7 +2086,6 @@ impl<'a, B: Bindgen> Generator<'a, B> {
                         id,
                     });
                 }
-                TypeDefKind::Map(..) => todo!(),
             },
         }
     }
@@ -2115,6 +2184,8 @@ impl<'a, B: Bindgen> Generator<'a, B> {
                 TypeDefKind::Type(t) => self.read_from_memory(t, addr, offset),
 
                 TypeDefKind::List(_) => self.read_list_from_memory(ty, addr, offset),
+                // Maps have the same linear memory layout as list<tuple<K, V>>.
+                TypeDefKind::Map(_, _) => self.read_list_from_memory(ty, addr, offset),
 
                 TypeDefKind::Future(_) | TypeDefKind::Stream(_) | TypeDefKind::Handle(_) => {
                     self.emit_and_lift(ty, addr, &I32Load { offset })
@@ -2216,7 +2287,6 @@ impl<'a, B: Bindgen> Generator<'a, B> {
                         id,
                     });
                 }
-                TypeDefKind::Map(..) => todo!(),
             },
         }
     }
@@ -2339,6 +2409,18 @@ impl<'a, B: Bindgen> Generator<'a, B> {
                     self.emit(&Instruction::GuestDeallocateList { element });
                 }
 
+                TypeDefKind::Map(key, value) => {
+                    let value_offset = self.bindgen.sizes().field_offsets([key, value])[1].0;
+                    self.push_block();
+                    self.emit(&IterBasePointer);
+                    let entry_addr = self.stack.pop().unwrap();
+                    self.deallocate_indirect(key, entry_addr.clone(), Default::default(), what);
+                    self.deallocate_indirect(value, entry_addr, value_offset, what);
+                    self.finish_block(0);
+
+                    self.emit(&Instruction::GuestDeallocateMap { key, value });
+                }
+
                 TypeDefKind::Handle(Handle::Own(_))
                 | TypeDefKind::Future(_)
                 | TypeDefKind::Stream(_)
@@ -2405,7 +2487,6 @@ impl<'a, B: Bindgen> Generator<'a, B> {
                 TypeDefKind::Unknown => unreachable!(),
 
                 TypeDefKind::FixedLengthList(..) => todo!(),
-                TypeDefKind::Map(..) => todo!(),
             },
         }
     }
@@ -2464,6 +2545,17 @@ impl<'a, B: Bindgen> Generator<'a, B> {
                     self.deallocate(ty, what);
                 }
 
+                TypeDefKind::Map(_, _) => {
+                    self.stack.push(addr.clone());
+                    self.emit(&Instruction::PointerLoad { offset });
+                    self.stack.push(addr);
+                    self.emit(&Instruction::LengthLoad {
+                        offset: offset + self.bindgen.sizes().align(ty).into(),
+                    });
+
+                    self.deallocate(ty, what);
+                }
+
                 TypeDefKind::Handle(Handle::Own(_))
                 | TypeDefKind::Future(_)
                 | TypeDefKind::Stream(_)
@@ -2527,7 +2619,6 @@ impl<'a, B: Bindgen> Generator<'a, B> {
                 TypeDefKind::Stream(_) => unreachable!(),
                 TypeDefKind::Unknown => unreachable!(),
                 TypeDefKind::FixedLengthList(_, _) => {}
-                TypeDefKind::Map(..) => todo!(),
             },
         }
     }

crates/core/src/lib.rs

@@ -166,6 +166,7 @@ pub trait InterfaceGenerator<'a> {
     fn type_alias(&mut self, id: TypeId, name: &str, ty: &Type, docs: &Docs);
     fn type_list(&mut self, id: TypeId, name: &str, ty: &Type, docs: &Docs);
     fn type_fixed_length_list(&mut self, id: TypeId, name: &str, ty: &Type, size: u32, docs: &Docs);
+    fn type_map(&mut self, id: TypeId, name: &str, key: &Type, value: &Type, docs: &Docs);
     fn type_builtin(&mut self, id: TypeId, name: &str, ty: &Type, docs: &Docs);
     fn type_future(&mut self, id: TypeId, name: &str, ty: &Option<Type>, docs: &Docs);
     fn type_stream(&mut self, id: TypeId, name: &str, ty: &Option<Type>, docs: &Docs);
@@ -203,7 +204,7 @@ where
         TypeDefKind::FixedLengthList(t, size) => {
             generator.type_fixed_length_list(id, name, t, *size, &ty.docs)
         }
-        TypeDefKind::Map(..) => todo!(),
+        TypeDefKind::Map(key, value) => generator.type_map(id, name, key, value, &ty.docs),
         TypeDefKind::Unknown => unreachable!(),
     }
 }
@@ -217,6 +218,7 @@ pub trait AnonymousTypeGenerator<'a> {
     fn anonymous_type_result(&mut self, id: TypeId, ty: &Result_, docs: &Docs);
     fn anonymous_type_list(&mut self, id: TypeId, ty: &Type, docs: &Docs);
     fn anonymous_type_fixed_length_list(&mut self, id: TypeId, ty: &Type, size: u32, docs: &Docs);
+    fn anonymous_type_map(&mut self, id: TypeId, key: &Type, value: &Type, docs: &Docs);
     fn anonymous_type_future(&mut self, id: TypeId, ty: &Option<Type>, docs: &Docs);
     fn anonymous_type_stream(&mut self, id: TypeId, ty: &Option<Type>, docs: &Docs);
     fn anonymous_type_type(&mut self, id: TypeId, ty: &Type, docs: &Docs);
@@ -242,7 +244,7 @@ pub trait AnonymousTypeGenerator<'a> {
             TypeDefKind::FixedLengthList(t, size) => {
                 self.anonymous_type_fixed_length_list(id, t, *size, &ty.docs)
             }
-            TypeDefKind::Map(..) => todo!(),
+            TypeDefKind::Map(key, value) => self.anonymous_type_map(id, key, value, &ty.docs),
             TypeDefKind::Unknown => unreachable!(),
         }
     }

crates/core/src/types.rs

@@ -261,7 +261,11 @@ impl Types {
             TypeDefKind::FixedLengthList(ty, _) => {
                 info = self.type_info(resolve, ty);
             }
-            TypeDefKind::Map(..) => todo!(),
+            TypeDefKind::Map(key, value) => {
+                info = self.type_info(resolve, key);
+                info |= self.type_info(resolve, value);
+                info.has_list = true;
+            }
             TypeDefKind::Unknown => unreachable!(),
         }
         let prev = self.type_info.insert(ty, info);

crates/cpp/src/lib.rs

@@ -2232,6 +2232,17 @@ impl<'a> wit_bindgen_core::InterfaceGenerator<'a> for CppInterfaceGenerator<'a>
         todo!("named fixed-length list types are not yet supported in the C++ backend")
     }
 
+    fn type_map(
+        &mut self,
+        _id: TypeId,
+        _name: &str,
+        _key: &wit_bindgen_core::wit_parser::Type,
+        _value: &wit_bindgen_core::wit_parser::Type,
+        _docs: &wit_bindgen_core::wit_parser::Docs,
+    ) {
+        todo!("map types are not yet supported in the C++ backend")
+    }
+
     fn type_builtin(
         &mut self,
         _id: TypeId,
@@ -3503,6 +3514,13 @@ impl<'a, 'b> Bindgen for FunctionBindgen<'a, 'b> {
             }
             abi::Instruction::AsyncTaskReturn { .. } => todo!(),
             abi::Instruction::DropHandle { .. } => todo!(),
+            abi::Instruction::MapLower { .. }
+            | abi::Instruction::MapLift { .. }
+            | abi::Instruction::IterMapKey { .. }
+            | abi::Instruction::IterMapValue { .. }
+            | abi::Instruction::GuestDeallocateMap { .. } => {
+                todo!("map types are not yet supported in this backend")
+            }
         }
     }
 

crates/csharp/src/function.rs

@@ -1468,6 +1468,11 @@ impl Bindgen for FunctionBindgen<'_, '_> {
             | Instruction::FixedLengthListLower { .. }
             | Instruction::FixedLengthListLowerToMemory { .. }
             | Instruction::FixedLengthListLiftFromMemory { .. }
+            | Instruction::MapLower { .. }
+            | Instruction::MapLift { .. }
+            | Instruction::IterMapKey { .. }
+            | Instruction::IterMapValue { .. }
+            | Instruction::GuestDeallocateMap { .. }
             => {
                 dbg!(inst);
                 todo!()

crates/csharp/src/interface.rs

@@ -1749,6 +1749,10 @@ impl<'a> CoreInterfaceGenerator<'a> for InterfaceGenerator<'a> {
         todo!("named fixed-length list types are not yet supported in the C# backend")
     }
 
+    fn type_map(&mut self, _id: TypeId, _name: &str, _key: &Type, _value: &Type, _docs: &Docs) {
+        todo!("map types are not yet supported in the C# backend")
+    }
+
     fn type_builtin(&mut self, _id: TypeId, _name: &str, _ty: &Type, _docs: &Docs) {
         unimplemented!();
     }

crates/go/src/lib.rs

@@ -2980,6 +2980,10 @@ const (
         uwriteln!(self.src, "{docs}type {name} = [{size}]{ty}");
     }
 
+    fn type_map(&mut self, _id: TypeId, _name: &str, _key: &Type, _value: &Type, _docs: &Docs) {
+        todo!("map types are not yet supported in the Go backend")
+    }
+
     fn type_builtin(&mut self, id: TypeId, name: &str, ty: &Type, docs: &Docs) {
         _ = (id, name, ty, docs);
         todo!()

crates/guest-rust/macro/src/lib.rs

@@ -111,6 +111,7 @@ impl Parse for Config {
                     Opt::Ownership(ownership) => opts.ownership = ownership,
                     Opt::Skip(list) => opts.skip.extend(list.iter().map(|i| i.value())),
                     Opt::RuntimePath(path) => opts.runtime_path = Some(path.value()),
+                    Opt::MapType(path) => opts.map_type = Some(path.value()),
                     Opt::BitflagsPath(path) => opts.bitflags_path = Some(path.value()),
                     Opt::Stubs => {
                         opts.stubs = true;
@@ -304,6 +305,7 @@ mod kw {
     syn::custom_keyword!(inline);
     syn::custom_keyword!(ownership);
     syn::custom_keyword!(runtime_path);
+    syn::custom_keyword!(map_type);
     syn::custom_keyword!(bitflags_path);
     syn::custom_keyword!(exports);
     syn::custom_keyword!(stubs);
@@ -383,6 +385,7 @@ enum Opt {
     Skip(Vec<syn::LitStr>),
     Ownership(Ownership),
     RuntimePath(syn::LitStr),
+    MapType(syn::LitStr),
     BitflagsPath(syn::LitStr),
     Stubs,
     ExportPrefix(syn::LitStr),
@@ -486,6 +489,10 @@ impl Parse for Opt {
             input.parse::<kw::runtime_path>()?;
             input.parse::<Token![:]>()?;
             Ok(Opt::RuntimePath(input.parse()?))
+        } else if l.peek(kw::map_type) {
+            input.parse::<kw::map_type>()?;
+            input.parse::<Token![:]>()?;
+            Ok(Opt::MapType(input.parse()?))
         } else if l.peek(kw::bitflags_path) {
             input.parse::<kw::bitflags_path>()?;
             input.parse::<Token![:]>()?;