From d613b1972ac69b17e69eed87b2e184d8475339a3 Mon Sep 17 00:00:00 2001
From: Luke Wagner <mail@lukewagner.name>
Date: Fri, 16 Jun 2023 18:20:44 -0500
Subject: [PATCH] Update Explainer.md to match Wit interface id changes in
 Binary.md

---
 design/mvp/Binary.md                          |  37 +--
 design/mvp/Explainer.md                       | 229 +++++-------------
 design/mvp/Subtyping.md                       |   2 +-
 design/mvp/WIT.md                             |   9 +-
 design/mvp/examples/LinkTimeVirtualization.md |  23 +-
 5 files changed, 95 insertions(+), 205 deletions(-)

diff --git a/design/mvp/Binary.md b/design/mvp/Binary.md
index b503793e..c74af5cb 100644
--- a/design/mvp/Binary.md
+++ b/design/mvp/Binary.md
@@ -102,8 +102,9 @@ Notes:
   for aliases (below).
 * Validation of `core:instantiatearg` initially only allows the `instance`
   sort, but would be extended to accept other sorts as core wasm is extended.
-* Validation of `instantiate` requires that `name` is present in an
-  `externname` of `c` (with a matching type).
+* Validation of `instantiate` requires that each `<name>` or `<iid>` in an
+  imported `externname` in `c` matches a `string` in a `with` argument and that
+  the argument's type matches the import's type.
 * When validating `instantiate`, after each individual type-import is supplied
   via `with`, the actual type supplied is immediately substituted for all uses
   of the import, so that subsequent imports and all exports are now specialized
@@ -327,23 +328,14 @@ flags are set.
 (See [Import and Export Definitions](Explainer.md#import-and-export-definitions)
 in the explainer.)
 ```
-import      ::= en:<externname> ed:<externdesc>                => (import en ed)
-export      ::= en:<externname> si:<sortidx> ed?:<externdesc>? => (export en si ed?)
-externname  ::= 0x00 n:<name>                                  => n
-              | 0x01 n:<id>                                    => (interface n)
-id          ::= len:<u32> n:<id-chars>                         => n (if len = |n|)
-
-id-chars ::= ns:<label> ':' pkg:<label> '/' n:<label> v:<id-version>   => ns:pkg/nv
-id-version ::=                                                         => ϵ
-             | '@' version:<version> pre:<verpre> build:<verbuild>     => version pre build
-
-version ::= major:<num> '.' minor:<num> '.' patch:<num>                => major.minor.patch
-version-number ::= digit+:[0x30-0x39]                                  => char(digit)+
-
-verpre ::=                                                             => ϵ
-         | '-' (a:<label> '.') b:<label>                               => -(a.*)b
-verbuild ::=                                                           => ϵ
-           | '+' (a:<label> '.') b:<label>                             => +(a.*)b
+import      ::= en:<externname> ed:<externdesc>                      => (import en ed)
+export      ::= en:<externname> si:<sortidx> ed?:<externdesc>?       => (export en si ed?)
+externname  ::= 0x00 n:<name>                                        => n
+              | 0x01 iid:<iid>                                       => (interface iid)
+iid         ::= len:<u32> c:<iid-chars>                              => c (if len = |c|)
+iid-chars   ::= ns:<label> ':' pkg:<label> '/' n:<label> v:<version> => ns:pkg/nv
+version     ::=                                                      => ϵ
+              | '@' v:<valid semver>                                 => @v
 ```
 
 Notes:
@@ -351,9 +343,6 @@ Notes:
   definition and can be used by all subsequent definitions just like an alias.
 * Validation requires that all resource types transitively used in the type of an
   export are introduced by a preceding `importdecl` or `exportdecl`.
-* The "parses as a URL" condition is defined by executing the [basic URL
-  parser] with `char(b)*` as *input*, no optional parameters and non-fatal
-  validation errors (which coincides with definition of `URL` in JS and `rust-url`).
 * Validation requires any exported `sortidx` to have a valid `externdesc`
   (which disallows core sorts other than `core module`). When the optional
   `externdesc` immediate is present, validation requires it to be a supertype
@@ -364,7 +353,7 @@ Notes:
 * The `id` fields of `externname` (that are present) must independently be
   unique among imports and exports, respectively. (An import and export *may*
   have the same `id`.)
-* URLs are compared for equality by plain byte identity.
+* `<valid semver>` is as defined by [https://semver.org](https://semver.org/)
 
 ## Name Section
 
@@ -407,5 +396,3 @@ named once.
 
 [type-imports]: https://github.com/WebAssembly/proposal-type-imports/blob/master/proposals/type-imports/Overview.md
 [module-linking]: https://github.com/WebAssembly/module-linking/blob/main/proposals/module-linking/Explainer.md
-
-[Basic URL Parser]: https://url.spec.whatwg.org/#concept-basic-url-parser
diff --git a/design/mvp/Explainer.md b/design/mvp/Explainer.md
index 7f34e428..62314c6e 100644
--- a/design/mvp/Explainer.md
+++ b/design/mvp/Explainer.md
@@ -191,8 +191,8 @@ more restricted version of `name`:
 instance       ::= (instance <id>? <instanceexpr>)
 instanceexpr   ::= (instantiate <componentidx> <instantiatearg>*)
                  | <inlineexport>*
-instantiatearg ::= (with <name> <sortidx>)
-                 | (with <name> (instance <inlineexport>*))
+instantiatearg ::= (with <string> <sortidx>)
+                 | (with <string> (instance <inlineexport>*))
 sortidx        ::= (<sort> <u32>)
 sort           ::= core <core:sort>
                  | func
@@ -200,7 +200,8 @@ sort           ::= core <core:sort>
                  | type
                  | component
                  | instance
-inlineexport   ::= (export <name> <sortidx>)
+inlineexport   ::= (export <externname> <sortidx>)
+string         ::= <core:name>
 name           ::= <label>
                  | [constructor]<label>
                  | [method]<label>.<label>
@@ -267,14 +268,14 @@ instance, the `core export` of a core module instance and a definition of an
 `outer` component (containing the current component):
 ```
 alias            ::= (alias <aliastarget> (<sort> <id>?))
-aliastarget      ::= export <instanceidx> <name>
+aliastarget      ::= export <instanceidx> <string>
                    | core export <core:instanceidx> <core:name>
                    | outer <u32> <u32>
 ```
 If present, the `id` of the alias is bound to the new index added by the alias
 and can be used anywhere a normal `id` can be used.
 
-In the case of `export` aliases, validation ensures `name` is an export in the
+In the case of `export` aliases, validation ensures `string` is an export in the
 target instance and has a matching sort.
 
 In the case of `outer` aliases, the `u32` pair serves as a [de Bruijn
@@ -1139,7 +1140,7 @@ Using canonical function definitions, we can finally write a non-trivial
 component that takes a string, does some logging, then returns a string.
 ```wasm
 (component
-  (import "logging" (id "wasi:logging") (instance $logging
+  (import "logging" (instance $logging
     (export "log" (func (param string)))
   ))
   (import "libc" (core module $Libc
@@ -1154,14 +1155,14 @@ component that takes a string, does some logging, then returns a string.
   (core module $Main
     (import "libc" "memory" (memory 1))
     (import "libc" "realloc" (func (param i32 i32) (result i32)))
-    (import "wasi:logging" "log" (func $log (param i32 i32)))
+    (import "logging" "log" (func $log (param i32 i32)))
     (func (export "run") (param i32 i32) (result i32)
       ... (call $log) ...
     )
   )
   (core instance $main (instantiate $Main
     (with "libc" (instance $libc))
-    (with "wasi:logging" (instance (export "log" (func $log))))
+    (with "logging" (instance (export "log" (func $log))))
   ))
   (func $run (param string) (result string) (canon lift
     (core func $main "run")
@@ -1314,7 +1315,9 @@ Lastly, imports and exports are defined as:
 ```
 import     ::= (import <externname> bind-id(<externdesc>))
 export     ::= (export <id>? <externname> <sortidx> <externdesc>?)
-externname ::= <name> (id <URL>)?
+externname ::= <name>
+             | (interface "<iid>")
+iid        ::= <label>:<label>/<label>(@<valid semver>)?
 ```
 Both import and export definitions append a new element to the index space of
 the imported/exported `sort` which can be optionally bound to an identifier in
@@ -1353,142 +1356,53 @@ the standard [avoidance problem] that appears in module systems with abstract
 types. In particular, it ensures that a client of a component is able to
 externally define a type compatible with the exports of the component.
 
-Components split the single externally-visible name of imports and exports into
-two sub-fields: a kebab-case `name` (as defined [above](#instance-definitions))
-and an `id` field that contains a URL (as defined by the [URL Standard], noting
-that, in this URL Standard, the term "URL" subsumes what has historically been
-called a [URI], including URLs that "identify" as opposed to "locate"). This
-subdivision of external names allows component producers to represent a variety
-of intentions for how a component is to be instantiated and executed so that a
-variety of hosts can portably execute the component.
-
-The `name` field of `externname` is required to be unique between all the imports
-and exports of a component definition, component type or instance type. Thus, a
-single `name` can be used to unambiguously select any import or export. Based on
-this, `with` and `alias` can use a `name` (not `externname`) to select an
-import or export. The uniqueness between imports and exports ensures that Wit
-and language bindings don't have to worry about separately namespacing imports
-and exports.
-
-In guest source-code bindings, the `name` is meant to be translated to
-source-language identifiers (applying case-conversion, as described
-[above](#instance-definitions)) attached to whatever source-language constructs
-represent the imports and exports (functions, globals, types, classes, etc).
-For example, given an import in a component type:
-```
-(import "one-two" (instance
-  (export "three-four" (func (param string) (result string)))
-))
-```
-a Rust bindings generator for a component targeting this type could produce an
-`extern crate one_two` containing the function `three_four`. Similarly, a
-[JS Embedding](#js-embedding) could allow `import {threeFour} from 'one-two'`
-to resolve to the imported function. Conversely, given an export in a component
-type:
-```
-(export "one-two" (instance
-  (export "three-four" (func (param string) (result string)))
-))
-```
-a Rust bindings generator for a component with this export could produce a
-trait `OneTwo` requiring a function `three_four` while the JS Embedding would
-expect the JS module implementing this component type to export a variable
-`oneTwo` containing an object with a field `threeFour` containing a function.
-
-The `name` field can also be used by *host* source-code bindings, defining the
-source-language identifiers that are to be used when instantiating a component
-and accessing its exports. For example, the [JS API]'s
-[`WebAssembly.instantiate()`] would use import `name`s in the [*read the
-imports*] step and use export `name`s in the [*create an exports object*] step.
-
-The optional `id` field of `externname` allows a component author to refer to
-an *externally-defined* specification of what an import "wants" or what an
-export has "implemented". One example is a URL naming a standard interface such
-as `wasi:filesystem` (assuming that WASI registered the `wasi:` URI scheme with
-IANA). Pre-standard, non-standard or proprietary interfaces could be referred
-to by an `https:` URL in an interface registry. For imports, a URL could
-alternatively refer to a *particular implementation* (e.g., at a hosted storage
-location) or a *query* for a *set of possible implementations* (e.g., using the
-query API of a public registry). Because of the wide variety of hosts executing
-components, the Component Model doesn't specify how URLs are to be interpreted,
-just that they are grammatically URLs. Even `https:` URLs may or may not be
-literally fetched by the host (c.f. [import maps]).
-
-The URLs of present `id` fields must *also* be unique (*in addition* the
-abovementioned uniqueness of `name`s). Thus, a URL can *also* be used to
-uniquely identify the subset of imports or exports that have URLs.
-
-While the `name` field is meant for source-code bindings generators, the `id`
-field is meant for automated interpretation by hosts and toolchains. In
-particular, hosts are expected to identify their host-implemented imports and
-host-called exports by URL, not `name`. This allows hosts to implement a
-wide collection of independently-developed interfaces where `name`s are chosen
-for developer ergonomics (and name collisions are handled independently in
-the binding generators, which is needed in any case) and URLs to serve as
-the invariant identifier that concretely links the guest to host. If there was
-only a `name`, interface authors would be forced to implicitly coordinate
-across the ecosystem to avoid collisions (which in general, isn't possible)
-while if there was only a URL, the developer-friendly identifiers would have
-to be specified manually by every developer or derived in an ad hoc fashion
-from the URL, whose contents may vary widely. This dual-name scheme is thus
-proposed to resolve these competing requirements.
-
-Inside the component model, this dual-name scheme shows up in [subtyping](#Subtyping.md),
-where the component subtyping simply ignores the `name` field when the `id`
-field is present. For example, the component:
-```
-(component
-  (import "fs" (id "wasi:filesystem") ...)
-)
-```
-can be supplied for the `x` import of the component:
-```
-(component
-  (import "x" (component
-    (import "filesystem" (id "wasi:filesystem") ...)
-  ))
-)
-```
-because the `name`s are ignored and the `id`s match. This subtyping is
-symmetric to what was described above for hosts, allowing components to
-serve as the "host" of other components, enabling [virtualization](examples/LinkTimeVirtualization.md).
-
-Since the concrete artifacts defining the host/guest interface is a collection
-of [Wit files](WIT.md), Wit must naturally allow interface authors to specify
-both the `name` and `id` of component imports and exports. While the syntax is
-still very much [in flux](https://github.com/WebAssembly/component-model/pull/83),
-a hypothetical simplified interface between a guest and host might look like:
-```
-// wasi:cli/Command
-default world Command {
-  import fs: "wasi:filesystem"
-  import console: "wasi:cli/console"
-  export main: "wasi:cli/main"
-}
-```
-where `wasi:filesystem`, `wasi:cli/console` and `wasi:cli/main` are separately
-defined interfaces that map to instance types. This "World" definition then
-maps to the following component type:
-```
-(component $Command
-  (import "fs" (id "wasi:filesystem") (instance ... filesystem function exports ...))
-  (import "console" (id "wasi:cli/console") (instance ... log function exports ...))
-  (export "main" (id "wasi:cli/main") (instance (export "main" (func ...))))
-)
-```
-A component *targeting* `wasi:cli/Command` would thus need to be a *subtype* of
-`$Command` (importing a subset of these imports and exporting a superset of
-these exports) while a host *supporting* `wasi:cli/Command` would need to be
-a *supertype* of `$Command` (offering a superset of these imports and expecting
-to call a subset of these exports).
-
-Importantly, this `wasi:cli/Command` World has been able to define the short
-developer-facing names like `fs` and `console` without worrying if there are
-any other Worlds that conflict with these names. If a host wants to implement
-`wasi:cli/command` and some other World that also happens to pick `fs`, either
-the `id` fields are the same, and so the two imports can be unified, or the
-`id` fields are different, and the host supplies two distinct imports,
-identified by URL.
+Components provide two options for externally naming imports and exports:
+* a kebab-name, defined [above](#instance-definitions)
+* an *interface identifier*, defined to be a tuple of namespace name, package
+  name, interface name and, optionally, a semantic version.
+
+The kebab-name option is meant to be used when the meaning of the import or
+export is specific and unique to the containing component. Kebab-named exports
+are expected to be explicitly invoked by a client who has read the
+documentation to know what the export does and how to invoke it. This matches
+the normal situation for reusable packages published in a registry. Similarly,
+kebab-named imports represent component-specific callbacks, hooks or
+configuration that are meant to be explicitly supplied by a client who has read
+the documentation to know what they mean.
+
+In contrast, the interface identifier option allows a component to refer to an
+externally-specified interface so that hosts or tooling can automatically know
+what the component wants to import or how the component wants to be called
+without requiring any manual developer intervention. For example, a component
+could import `(interface "wasi:filesystem/types")` to request an implementation
+of a WASI-standardized filesystem. Or, a component could export
+`(interface "wasi:http/handler")` to tell the host to invoke the component in
+response to arriving HTTP requests.
+
+The namespace, package and interface name subfields of the interface identifier
+are meant to be resolved by some external mechanism such as a directory
+structure or a registry. However done, the identifier is expected to resolve to
+an [Wit-encoded type](WIT.md#binary-format) that must be [compatible](Subtyping.md)
+with the type of the import or export declared inside the component. Since this
+compatibility is relative to the name resolution context, compatibility
+checking is not included in basic component validation but, rather, is expected
+to be part of higher-level workflows (such as publication of a component to a
+registry), once the name-resolution context is fixed. Importantly, interface
+identifiers resolve to *types*, not *implementations*. Independently, a host or
+composition tool gets to select the specific implementation and the component
+importing or exporting the interface has no say in what that implementation is
+or whether the implementation is native host code or another component.
+
+Kebab names are required to be unique between all the imports and exports in a
+single component definition, component type or instance type, so that a single
+kebab-name uniquely identifies one import or export. Interface identifiers are
+also required to be unique, but only between imports or exports separately
+(i.e., a single interface identifier can be both imported and exported, while a
+single kebab name can't). Because interface identifiers always contain a colon
+(`:`), kebab-names and interface identifiers form a disjoint set of strings and
+thus the `string` literal of a `with` argument always matches at most one
+import and the `string` literal of an `alias export` always matches at most one
+export.
 
 
 ## Component Invariants
@@ -1558,15 +1472,12 @@ instantiated module, `WebAssembly.instantiate` would always produce a
 `WebAssembly.Instance` object for both module and component arguments
 (again, with kebab-case component export names converted to lowerCamelCase).
 
-Since the JavaScript embedding is generic, loading all component types, it
-needs to allow the JS client to refer to either of the `name` or `URL` fields
-of component `externname`s. On the import side, this means that, when a `URL`
-is present, *read the imports* will first attempt to [`Get`] the `URL` and, on
-failure, `Get` the `name`. On the export side, this means that *both* the
-`name` and `URL` are exposed as exports in the export object (both holding the
-same value). Since `name` and `URL` are necessarily disjoint sets of strings
-(in particular, `URL`s must contain a `:`, `name` must not), there should not
-be any conflicts in either of these cases.
+When `interface` imports or exports are used, the `iid` string is used in place
+of the kebab-name. Core WebAssembly modules allow arbitrary UTF-8 in
+import/export strings, so the union of kebab-names and interface identifiers
+(which is disjoint) allow components to express a subset of the possible Core
+WebAssembly import/export strings, which means that all component import/export
+names can be instantiated and called using the existing JS API.
 
 Types are a new sort of definition that are not ([yet][type-imports]) present
 in Core WebAssembly and so the [*read the imports*] and [*create an exports
@@ -1711,10 +1622,8 @@ the same places where modules can be loaded today, branching on the `layer`
 field in the binary format to determine whether to decode as a module or a
 component.
 
-When the `URL` field of an imported `externname` is present, the `URL` is
-used as the module specifier, using the same resolution path as JS module.
-Otherwise, the `name` field is used as the module specifier, which requires
-[Import Maps] support to resolve to a `URL`.
+TODO: ESM-integration for `interface` imports and exports is still being
+worked out in detail.
 
 The main question is how to deal with component imports having a
 single string as well as the new importable component, module and instance
@@ -1858,10 +1767,6 @@ and will be added over the coming months to complete the MVP proposal:
 [Avoidance Problem]: https://counterexamples.org/avoidance.html
 [Non-Parametric Parametricity]: https://people.mpi-sws.org/~dreyer/papers/npp/main.pdf
 
-[URL Standard]: https://url.spec.whatwg.org
-[URI]: https://en.wikipedia.org/wiki/Uniform_Resource_Identifier
-[Import Maps]: https://wicg.github.io/import-maps/
-
 [module-linking]: https://github.com/WebAssembly/module-linking/blob/main/design/proposals/module-linking/Explainer.md
 [interface-types]: https://github.com/WebAssembly/interface-types/blob/main/proposals/interface-types/Explainer.md
 [type-imports]: https://github.com/WebAssembly/proposal-type-imports/blob/master/proposals/type-imports/Overview.md
diff --git a/design/mvp/Subtyping.md b/design/mvp/Subtyping.md
index 2dd22b44..c6365fc0 100644
--- a/design/mvp/Subtyping.md
+++ b/design/mvp/Subtyping.md
@@ -19,7 +19,7 @@ But roughly speaking:
 | `union`                   | `T <: (union ... T ...)` |
 | `own`, `borrow`           | none (although resource subtyping may be introduced in the future which would imply handle subtyping) |
 | `func`                    | parameter names must match in order; contravariant parameter subtyping; superfluous parameters can be ignored in the subtype; `option` parameters can be ignored in the supertype; covariant result subtyping |
-| `component`               | all imports in the subtype must be present in the supertype with matching types; all exports in the supertype must be present in the subtype; the `URL` is treated as the complete name, when present, ignoring the `name` field |
+| `component`               | all imports in the subtype must be present in the supertype with matching types; all exports in the supertype must be present in the subtype |
 
 The remaining specialized value types inherit their subtyping from their
 fundamental value types.
diff --git a/design/mvp/WIT.md b/design/mvp/WIT.md
index cbd51b36..319a7d5c 100644
--- a/design/mvp/WIT.md
+++ b/design/mvp/WIT.md
@@ -728,14 +728,11 @@ WIT files optionally start with a package declaration which defines the ID of
 the package.
 
 ```ebnf
-package-decl        ::= 'package' id ':' id ('@' version)?
-version             ::= integer '.' integer '.' integer version-pre-release? version-build?
-version-pre-release ::= '-' (id '.')* id
-version-build       ::= '+' (id '.')* id
+package-decl        ::= 'package' id ':' id ('@' valid-semver)?
 ```
 
-Note that the version, specified with `@`, is optional. Otherwise the first `id`
-is the namespace and the second `id` is the package name.
+The production `valid-semver` is as defined by
+[Semantic Versioning 2.0](https://semver.org/) and optional.
 
 ## Item: `toplevel-use`
 
diff --git a/design/mvp/examples/LinkTimeVirtualization.md b/design/mvp/examples/LinkTimeVirtualization.md
index 2af28970..0e2d4b57 100644
--- a/design/mvp/examples/LinkTimeVirtualization.md
+++ b/design/mvp/examples/LinkTimeVirtualization.md
@@ -2,9 +2,10 @@
 
 The idea with **link-time virtualization** use cases is to take the static
 dependency graph on the left (where all 3 components import the
-`wasi:filesystem` interface) and produce the runtime instance graph on the
-right, where the `parent` instance has created a `virtualized` instance and
-supplied it to a new `child` instance as the `wasi:filesystem` implementation.
+`wasi:filesystem/types` interface) and produce the runtime instance graph on
+the right, where the `parent` instance has created a `virtualized` instance and
+supplied it to a new `child` instance as the `wasi:filesystem/types`
+implementation.
 
 <p align="center"><img src="./images/link-time-virtualization.svg" width="500"></p>
 
@@ -16,7 +17,7 @@ without regard to `parent.wasm`:
 ```wasm
 ;; child.wat
 (component
-  (import "wasi:filesystem" (instance
+  (import (interface "wasi:filesystem/types") (instance
     (export "read" (func ...))
     (export "write" (func ...))
   ))
@@ -30,7 +31,7 @@ out and reused as a separate component:
 ```wasm
 ;; virtualize.wat
 (component
-  (import "wasi:filesystem" (instance $fs
+  (import (interface "wasi:filesystem/types") (instance $fs
     (export "read" (func ...))
     (export "write" (func ...))
   ))
@@ -48,14 +49,14 @@ We now write the parent component by composing `child.wasm` with
 ```wasm
 ;; parent.wat
 (component
-  (import "wasi:filesystem" (instance $real-fs ...))
+  (import (interface "wasi:filesystem/types") (instance $real-fs ...))
   (import "./virtualize.wasm" (component $Virtualize ...))
   (import "./child.wasm" (component $Child ...))
   (instance $virtual-fs (instantiate (component $Virtualize)
-    (with "wasi:filesystem" (instance $real-fs))
+    (with "wasi:filesystem/types" (instance $real-fs))
   ))
   (instance $child (instantiate (component $Child)
-    (with "wasi:filesystem" (instance $virtual-fs))
+    (with "wasi:filesystem/types" (instance $virtual-fs))
   ))
 )
 ```
@@ -65,14 +66,14 @@ definitions in place of imports:
 ```wasm
 ;; parent.wat
 (component
-  (import "wasi:filesystem" (instance $real-fs ...))
+  (import (interface "wasi:filesystem/types") (instance $real-fs ...))
   (component $Virtualize ... copied inline ...)
   (component $Child ... copied inline ...)
   (instance $virtual-fs (instantiate (component $Virtualize)
-    (with "wasi:filesystem" (instance $real-fs))
+    (with "wasi:filesystem/types" (instance $real-fs))
   ))
   (instance $child (instantiate (component $Child)
-    (with "wasi:filesystem" (instance $virtual-fs))
+    (with "wasi:filesystem/types" (instance $virtual-fs))
   ))
 )
 ```