From ed01810e10acc31cde8dd2529ffda2e8409b4abb Mon Sep 17 00:00:00 2001
From: Luke Wagner <mail@lukewagner.name>
Date: Wed, 13 Aug 2025 17:28:03 -0500
Subject: [PATCH 1/2] Add a 'map' type

Resolves #125
---
 design/mvp/Binary.md                    |  1 +
 design/mvp/CanonicalABI.md              |  1 +
 design/mvp/Explainer.md                 | 13 +++++++++++++
 design/mvp/WIT.md                       | 13 +++++++++++++
 design/mvp/canonical-abi/definitions.py |  6 ++++++
 design/mvp/canonical-abi/run_tests.py   |  4 ++++
 6 files changed, 38 insertions(+)

diff --git a/design/mvp/Binary.md b/design/mvp/Binary.md
index 590a3924..3ec5acfb 100644
--- a/design/mvp/Binary.md
+++ b/design/mvp/Binary.md
@@ -206,6 +206,7 @@ defvaltype    ::= pvt:<primvaltype>                       => pvt
                 | 0x68 i:<typeidx>                        => (borrow i)
                 | 0x66 t?:<valtype>?                      => (stream t?) 🔀
                 | 0x65 t?:<valtype>?                      => (future t?) 🔀
+                | 0x63 k:<valtype> v:<valtype>            => (map k v) (if k is in <keytype>) 🗺️
 labelvaltype  ::= l:<label'> t:<valtype>                  => l t
 case          ::= l:<label'> t?:<valtype>? 0x00           => (case l t?)
 label'        ::= len:<u32> l:<label>                     => l    (if len = |l|)
diff --git a/design/mvp/CanonicalABI.md b/design/mvp/CanonicalABI.md
index 289b673d..dcac0c3b 100644
--- a/design/mvp/CanonicalABI.md
+++ b/design/mvp/CanonicalABI.md
@@ -1661,6 +1661,7 @@ def despecialize(t):
     case EnumType(labels)    : return VariantType([ CaseType(l, None) for l in labels ])
     case OptionType(t)       : return VariantType([ CaseType("none", None), CaseType("some", t) ])
     case ResultType(ok, err) : return VariantType([ CaseType("ok", ok), CaseType("error", err) ])
+    case MapType(k, v)       : return ListType(despecialize(TupleType([k, v])))
     case _                   : return t
 ```
 The specialized value types `string` and `flags` are missing from this list
diff --git a/design/mvp/Explainer.md b/design/mvp/Explainer.md
index 1d447f99..8ad3ce45 100644
--- a/design/mvp/Explainer.md
+++ b/design/mvp/Explainer.md
@@ -57,6 +57,7 @@ implemented, considered stable and included in a future milestone:
 * 🔧: fixed-length lists
 * 📝: the `error-context` type
 * 🔗: canonical interface names
+* 🗺️: `map` type
 
 (Based on the previous [scoping and layering] proposal to the WebAssembly CG,
 this repo merges and supersedes the [module-linking] and [interface-types]
@@ -560,12 +561,14 @@ defvaltype    ::= bool
                 | (enum "<label>"+)
                 | (option <valtype>)
                 | (result <valtype>? (error <valtype>)?)
+                | (map <keytype> <valtype>) 🗺️
                 | (own <typeidx>)
                 | (borrow <typeidx>)
                 | (stream <typeidx>?) 🔀
                 | (future <typeidx>?) 🔀
 valtype       ::= <typeidx>
                 | <defvaltype>
+keytype       ::= bool | s8 | u8 | s16 | u16 | s32 | u32 | s64 | u64 | char | string 🗺️
 resourcetype  ::= (resource (rep i32) (dtor async? <funcidx> (callback <funcidx>)?)?)
 functype      ::= (func (param "<label>" <valtype>)* (result <valtype>)?)
 componenttype ::= (component <componentdecl>*)
@@ -765,6 +768,7 @@ defined by the following mapping:
                     (option <valtype>) ↦ (variant (case "none") (case "some" <valtype>))
 (result <valtype>? (error <valtype>)?) ↦ (variant (case "ok" <valtype>?) (case "error" <valtype>?))
                                 string ↦ (list char)
+             (map <keytype> <valtype>) ↦ (list (tuple <keytype> <valtype>))
 ```
 
 Specialized value types have the same set of semantic values as their
@@ -780,6 +784,14 @@ this can sometimes allow values to be represented differently. For example,
 `flags` in the Canonical ABI uses a bit-vector while an equivalent record
 of boolean fields uses a sequence of boolean-valued bytes.
 
+Since a `map` is a specialization of a list of (key, value) pairs without any
+additional semantic guarantee of key uniqueness, the Component Model does not
+forcibly prevent duplicate keys from appearing in the list. In the case of
+duplicate keys, the expectation for bindings generators is that for any given
+key, the *last* (key, value) pair in the list defines the value of the key in
+the map. To simplify bindings generation, `<keytype>`s is a conservative subset
+of `<valtype>`, but this subset could be expanded over time based on use cases.
+
 Note that, at least initially, variants are required to have a non-empty list of
 cases. This could be relaxed in the future to allow an empty list of cases, with
 the empty `(variant)` effectively serving as an [empty type] and indicating
@@ -2793,6 +2805,7 @@ At a high level, the additional coercions would be:
 | `enum` | same as [`enum`] | same as [`enum`] |
 | `option` | same as [`T?`] | same as [`T?`] |
 | `result` | same as `variant`, but coerce a top-level `error` return value to a thrown exception | same as `variant`, but coerce uncaught exceptions to top-level `error` return values |
+| `map` | `new Map(_)` | `Map`s directly or other objects via `Object.entries(_)` |
 | `own`, `borrow` | see below | see below |
 | `future` | to a `Promise` | from a `Promise` |
 | `stream` | to a `ReadableStream` | from a `ReadableStream` |
diff --git a/design/mvp/WIT.md b/design/mvp/WIT.md
index 313d6770..4d6f0279 100644
--- a/design/mvp/WIT.md
+++ b/design/mvp/WIT.md
@@ -1021,6 +1021,7 @@ keyword ::= 'as'
           | 'include'
           | 'interface'
           | 'list'
+          | 'map'
           | 'option'
           | 'own'
           | 'package'
@@ -1712,6 +1713,7 @@ ty ::= 'u8' | 'u16' | 'u32' | 'u64'
      | list
      | option
      | result
+     | map
      | handle
      | future
      | stream
@@ -1733,6 +1735,11 @@ result ::= 'result' '<' ty ',' ty '>'
          | 'result' '<' ty '>'
          | 'result'
 
+map ::= 'map' '<' kt ',' ty '>'
+kt ::= 'u8' | 'u16' | 'u32' | 'u64'
+     | 's8' | 's16' | 's32' | 's64'
+     | 'char' | 'bool' | 'string'
+
 future ::= 'future' '<' ty '>'
          | 'future'
 
@@ -1772,6 +1779,12 @@ variant result {
 These types are so frequently used and frequently have language-specific
 meanings though so they're also provided as first-class types.
 
+🗺️ The `map` type is semantically equivalent to a list of pairs of keys and
+values but is meant to be represented by bindings generators in the source
+language as a mapping from keys to values (e.g., as an object, map, dictionary
+or hash table) where, in the case of duplicate keys, the last key's value is
+used.
+
 The `future` and `stream` types are described as part of the [async
 explainer](Async.md#streams-and-futures).
 
diff --git a/design/mvp/canonical-abi/definitions.py b/design/mvp/canonical-abi/definitions.py
index 62f6e9b3..92403026 100644
--- a/design/mvp/canonical-abi/definitions.py
+++ b/design/mvp/canonical-abi/definitions.py
@@ -156,6 +156,11 @@ class ResultType(ValType):
   ok: Optional[ValType]
   error: Optional[ValType]
 
+@dataclass
+class MapType(ValType):
+  k: ValType # <keytype>
+  v: ValType
+
 @dataclass
 class FlagsType(ValType):
   labels: list[str]
@@ -974,6 +979,7 @@ def despecialize(t):
     case EnumType(labels)    : return VariantType([ CaseType(l, None) for l in labels ])
     case OptionType(t)       : return VariantType([ CaseType("none", None), CaseType("some", t) ])
     case ResultType(ok, err) : return VariantType([ CaseType("ok", ok), CaseType("error", err) ])
+    case MapType(k, v)       : return ListType(despecialize(TupleType([k, v])))
     case _                   : return t
 
 ### Type Predicates
diff --git a/design/mvp/canonical-abi/run_tests.py b/design/mvp/canonical-abi/run_tests.py
index 131b947a..174fa1ff 100644
--- a/design/mvp/canonical-abi/run_tests.py
+++ b/design/mvp/canonical-abi/run_tests.py
@@ -343,6 +343,10 @@ def test_heap(t, expect, args, byte_array):
 test_heap(t, v, [0,2],
           [0xff,0xff,0xff,0xff, 0,0,0,0])
 
+t = MapType(U8Type(), U16Type())
+test_heap(t, [{'0':42, '1':83}, {'0':43, '1':84}], [0, 2],
+          [42,0xff,83,0, 43,0xff,84,0])
+
 def test_flatten(t, params, results):
   expect = CoreFuncType(params, results)
 

From 6661b85a2882191300e34b4d5fb343a6ea5c5c92 Mon Sep 17 00:00:00 2001
From: Luke Wagner <mail@lukewagner.name>
Date: Thu, 14 Aug 2025 15:15:39 -0500
Subject: [PATCH 2/2] Remove 'object' from description in WIT.md, add
 'associative array'

---
 design/mvp/WIT.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/design/mvp/WIT.md b/design/mvp/WIT.md
index 4d6f0279..62f0c175 100644
--- a/design/mvp/WIT.md
+++ b/design/mvp/WIT.md
@@ -1781,9 +1781,8 @@ meanings though so they're also provided as first-class types.
 
 🗺️ The `map` type is semantically equivalent to a list of pairs of keys and
 values but is meant to be represented by bindings generators in the source
-language as a mapping from keys to values (e.g., as an object, map, dictionary
-or hash table) where, in the case of duplicate keys, the last key's value is
-used.
+language as a mapping from keys to values (e.g., as an associative array or or
+hash table) where, in the case of duplicate keys, the last key's value is used.
 
 The `future` and `stream` types are described as part of the [async
 explainer](Async.md#streams-and-futures).