Add [implements=<I>]L for multiple imports

Extend the WIT `extern-type` grammar to allow `use-path` as a third case,
enabling `import id: use-path` and `export id: use-path` to create
plain-named imports/exports whose instance type matches a named interface.

This allows importing the same interface multiple times under different
plain names (e.g., `import primary: store; import secondary: store;`),
encoded using the `[implements=<interfacename>]label` annotation pattern.

Fixes #287

Co-authored-by: Luke Wagner <mail@lukewagner.name>

Author: ricochet

design/mvp/Binary.md

@@ -408,11 +408,15 @@ Notes:
   [text format](Explainer.md#import-and-export-definitions).
 * The `<importname>`s of a component must all be [strongly-unique]. Separately,
   the `<exportname>`s of a component must also all be [strongly-unique].
-* Validation requires that annotated `plainname`s only occur on `func` imports
-  or exports and that the first label of a `[constructor]`, `[method]` or
-  `[static]` matches the `plainname` of a preceding `resource` import or
-  export, respectively, in the same scope (component, component type or
-  instance type).
+* Validation requires that `[constructor]`, `[method]` and `[static]` annotated
+  `plainname`s only occur on `func` imports or exports and that the first label
+  of a `[constructor]`, `[method]` or `[static]` matches the `plainname` of a
+  preceding `resource` import or export, respectively, in the same scope
+  (component, component type or instance type).
+* Validation requires that `[implements=<I>]` annotated `plainname`s only
+  occur on `instance` imports or exports.
+* Validation requires that `interfacename`-named imports or exports are
+  `instance`-typed.
 * Validation of `[constructor]` names requires a `func` type whose result type
   is either `(own $R)` or `(result (own $R) E?)` where `$R` is a resource type
   labeled `r`.

design/mvp/Explainer.md

@@ -2538,6 +2538,7 @@ plainname         ::= <label>
                     | '[constructor]' <label>
                     | '[method]' <label> '.' <label>
                     | '[static]' <label> '.' <label>
+                    | '[implements=<' <interfacename> '>]' <label>
 label             ::= <first-fragment> ( '-' <fragment> )*
 first-fragment    ::= [a-z] <word>
                     | [A-Z] <acronym>
@@ -2683,6 +2684,31 @@ annotations trigger additional type-validation rules (listed in
 * Similarly, an import or export named `[method]R.foo` must be a function whose
   first parameter must be `(param "self" (borrow $R))`.
 
+When an instance import or export is annotated with `[implements=<I>]L`, it
+indicates that the instance implements interface `I` but is given the plain
+name `L`. This enables a component to import or export the same interface
+multiple times with different plain names. For example:
+
+```wat
+(component
+  (import "[implements=<wasi:keyvalue/store>]primary" (instance ...))
+  (import "[implements=<wasi:keyvalue/store>]secondary" (instance ...))
+)
+```
+
+Here, both imports implement `wasi:keyvalue/store` but have distinct plain
+names `primary` and `secondary`. Bindings generators can use the
+`[implements=<I>]` annotation to know which interface the instance implements,
+enabling them to share value type bindings across both imports. (Note that
+resource types defined in the interface, such as `bucket`, are treated as
+distinct for each import, since each may have a different implementation.)
+
+The `interfacename` also helps hosts and clients of a component. A host that
+sees `[implements=<wasi:keyvalue/store>]primary` knows to supply a
+`wasi:keyvalue/store` implementation for that import, even though the import
+name is just `primary`. Similarly, a client composing components can use the
+annotation to match compatible imports and exports across components.
+
 When a function's type is `async`, bindings generators are expected to
 emit whatever asynchronous language construct is appropriate (such as an
 `async` function in JS, Python or Rust). See the [concurrency explainer] for
@@ -2824,11 +2850,11 @@ Values]) are **strongly-unique**:
   * Strip any `[...]` annotation prefix from both names.
   * The names are strongly-unique if the resulting strings are unequal.
 
-Thus, the following names are strongly-unique:
-* `foo`, `foo-bar`, `[constructor]foo`, `[method]foo.bar`, `[method]foo.baz`
+Thus, the following set of names are strongly-unique and can thus all be imports (or exports) of the same component (or component type or instance type):
+* `foo`, `foo-bar`, `[constructor]foo`, `[method]foo.bar`, `[method]foo.baz`, `foo:bar/baz`, `[implements=<foo:bar/baz>]bar`, `[implements=<foo:bar/baz>]quux`
 
 but attempting to add *any* of the following names would be a validation error:
-* `foo`, `foo-BAR`, `[constructor]foo-BAR`, `[method]foo.foo`, `[method]foo.BAR`
+* `foo`, `foo-BAR`, `[constructor]foo-BAR`, `[method]foo.foo`, `[method]foo.BAR`, `[implements=<a:b/c>]foo`, `foo:bar/baz`, `bar`, `[implements=<x:y/z>]bar`
 
 Note that additional validation rules involving types apply to names with
 annotations. For example, the validation rules for `[constructor]foo` require

design/mvp/WIT.md

@@ -366,6 +366,31 @@ world union-my-world-b {
 }
 ```
 
+When a world being included contains plain-named imports or exports that
+reference a named interface (using the `id: use-path` syntax), the `with`
+keyword renames the plain-name label while preserving the underlying
+`[implements=<I>]` annotation in the encoding. For example:
+
+```wit
+package local:demo;
+
+interface store {
+    get: func(key: string) -> option<string>;
+}
+
+world base {
+    import cache: store;
+}
+
+world extended {
+    include base with { cache as my-cache }
+}
+```
+
+In this case, `extended` has a single import with the plain name `my-cache`
+that implements `local:demo/store`, equivalent to writing
+`import my-cache: store;` directly.
+
 `with` cannot be used to rename interface names, however, so the following
 world would be invalid:
 ```wit
@@ -1381,9 +1406,30 @@ export-item ::= 'export' id ':' extern-type
 import-item ::= 'import' id ':' extern-type
               | 'import' use-path ';'
 
-extern-type ::= func-type ';' | 'interface' '{' interface-items* '}'
+extern-type ::= func-type ';' | 'interface' '{' interface-items* '}' | use-path ';'
+```
+
+The third case of `extern-type` allows a named interface to be imported or
+exported with a custom [plain name]. For example:
+
+```wit
+world my-world {
+    import primary: wasi:keyvalue/store;
+    import secondary: wasi:keyvalue/store;
+    export my-handler: wasi:http/handler;
+}
 ```
 
+Here, `primary` and `secondary` are two distinct imports that both have the
+instance type of the `wasi:keyvalue/store` interface. The plain name of the
+import is the `id` before the colon (e.g., `primary`), not the interface name.
+This contrasts with `import wasi:keyvalue/store;` (without the `id :` prefix),
+which would create a single import using the full interface name
+`wasi:keyvalue/store`. Similarly, the export `my-handler` has the instance type
+of `wasi:http/handler` but uses the plain name `my-handler` instead of the full
+interface name, which is useful when a component wants to export the same
+interface multiple times or simply use a more descriptive name.
+
 Note that worlds can import types and define their own types to be exported
 from the root of a component and used within functions imported and exported.
 The `interface` item here additionally defines the grammar for IDs used to refer
@@ -2061,6 +2107,52 @@ This duplication is useful in the case of cross-package references or split
 packages, allowing a compiled `world` definition to be fully self-contained and
 able to be used to compile a component without additional type information.
 
+When a world imports or exports a named interface with a custom plain name
+(using the `id: use-path` syntax), the encoding uses the `[implements=<I>]`
+annotation defined in [Explainer.md](Explainer.md#import-and-export-definitions) to indicate which
+interface the instance implements. For example, the following WIT:
+
+```wit
+package local:demo;
+
+interface store {
+    get: func(key: string) -> option<string>;
+}
+
+world w {
+    import one: store;
+    import two: store;
+}
+```
+
+is encoded as:
+
+```wat
+(component
+  (type (export "w") (component
+    (export "local:demo/w" (component
+      (import "[implements=<local:demo/store>]one" (instance
+        (export "get" (func (param "key" string) (result (option string))))
+      ))
+      (import "[implements=<local:demo/store>]two" (instance
+        (export "get" (func (param "key" string) (result (option string))))
+      ))
+    ))
+  ))
+  (type (export "store") (component
+    (export "local:demo/store" (instance
+      (export "get" (func (param "key" string) (result (option string))))
+    ))
+  ))
+)
+```
+
+The `[implements=<local:demo/store>]` prefix tells bindings generators and
+toolchains which interface each plain-named instance import implements, while
+the labels `one` and `two` provide distinct plain names. This is a case of
+the general `[implements=<interfacename>]label` pattern described in
+[Explainer.md](Explainer.md#import-and-export-definitions).
+
 Putting this all together, the following WIT definitions:
 
 ```wit

test/wasm-tools/implements.wast

@@ -0,0 +1,78 @@
+;; RUN: wast --assert default --snapshot tests/snapshots %
+
+;; Valid: basic [implements=<...>] on instance import
+(component
+  (import "[implements=<a:b/c>]name" (instance))
+)
+
+;; Valid: [implements=<...>] on instance export
+(component
+  (instance $i)
+  (export "[implements=<a:b/c>]name" (instance $i))
+)
+
+;; Valid: two imports with the same interface, different labels
+(component
+  (import "[implements=<a:b/c>]one" (instance))
+  (import "[implements=<a:b/c>]two" (instance))
+)
+
+;; Valid: [implements=<...>] with version in interface name
+(component
+  (import "[implements=<a:b/c@1.2.3>]name" (instance))
+)
+
+;; Valid: [implements=<...>] alongside a bare interface import of the same interface
+(component
+  (import "a:b/c" (instance))
+  (import "[implements=<a:b/c>]alt" (instance))
+)
+
+;; Valid: in a component type
+(component
+  (type (component
+    (import "[implements=<a:b/c>]one" (instance
+      (export "get" (func (param "key" string) (result (option string))))
+    ))
+    (import "[implements=<a:b/c>]two" (instance
+      (export "get" (func (param "key" string) (result (option string))))
+    ))
+  ))
+)
+
+;; Invalid: [implements=<...>] on func (must be instance)
+(assert_invalid
+  (component
+    (import "[implements=<a:b/c>]name" (func))
+  )
+  "`[implements=<a:b/c>]` must be on an instance import or export")
+
+;; Invalid: [implements=<...>] on component (must be instance)
+(assert_invalid
+  (component
+    (import "[implements=<a:b/c>]name" (component))
+  )
+  "`[implements=<a:b/c>]` must be on an instance import or export")
+
+;; Invalid: duplicate labels after stripping annotation
+(assert_invalid
+  (component
+    (import "[implements=<a:b/c>]name" (instance))
+    (import "[implements=<x:y/z>]name" (instance))
+  )
+  "conflicts with previous name")
+
+;; Invalid: duplicate label between annotated and bare plain name
+(assert_invalid
+  (component
+    (import "name" (func))
+    (import "[implements=<a:b/c>]name" (instance))
+  )
+  "conflicts with previous name")
+
+;; Invalid: malformed interface name inside annotation
+(assert_invalid
+  (component
+    (import "[implements=<NotValid>]name" (instance))
+  )
+  "not a valid extern name")

test/wasm-tools/naming.wast

@@ -125,3 +125,34 @@
     (import "[static]a.a" (func))
   )
   "import name `[static]a.a` conflicts with previous name `a`")
+
+;; [implements=<...>] strong-uniqueness tests
+
+;; Valid: two [implements=<...>] with different labels are strongly-unique
+(component definition
+  (import "[implements=<a:b/c>]one" (instance))
+  (import "[implements=<a:b/c>]two" (instance))
+)
+
+;; Valid: [implements=<...>] and a bare interface name are strongly-unique
+;; (different name kinds: plainname vs interfacename)
+(component definition
+  (import "a:b/c" (instance))
+  (import "[implements=<a:b/c>]alt" (instance))
+)
+
+;; Invalid: two [implements=<...>] with the same label conflict
+(assert_invalid
+  (component
+    (import "[implements=<a:b/c>]name" (instance))
+    (import "[implements=<x:y/z>]name" (instance))
+  )
+  "conflicts with previous name")
+
+;; Invalid: [implements=<...>] label conflicts with a bare plain name
+(assert_invalid
+  (component
+    (import "name" (func))
+    (import "[implements=<a:b/c>]name" (instance))
+  )
+  "conflicts with previous name")