Clarify what's in Preview 2 (#255)

* Clarify what's in Preview 2

Resolves #229

* Split out package and interface id cases in the grammar

* Require the 'refines' immediate to be 0

Author: lukewagner

README.md

@@ -12,10 +12,9 @@ reference interpreter and test suite.
 
 ## Milestones
 
-The Component Model is being incrementally developed and stabilized as part of
-the overall [WASI preview process]. The current contents of this repo reflect
-the "Preview 2" milestone. The "Preview 3" milestone will be primarily
-concerned with the addition of [async support].
+The Component Model is currently being incrementally developed and stabilized
+as part of [WASI Preview 2]. The subsequent "Preview 3" milestone will be
+primarily concerned with the addition of [async support].
 
 ## Contributing
 
@@ -35,5 +34,5 @@ To contribute to any of these repositories, see the Community Group's
 [formal spec]: spec/
 [W3C WebAssembly Community Group]: https://www.w3.org/community/webassembly/
 [Contributing Guidelines]: https://webassembly.org/community/contributing/
-[WASI preview process]: https://github.com/WebAssembly/meetings/blob/main/wasi/2023/presentations/2023-02-09-gohman-wasi-roadmap.pdf
+[WASI Preview 2]: https://github.com/WebAssembly/WASI/tree/main/preview2
 [Async Support]: https://docs.google.com/presentation/d/1MNVOZ8hdofO3tI0szg_i-Yoy0N2QPU2C--LzVuoGSlE/edit?usp=share_link

design/mvp/Binary.md

@@ -12,6 +12,8 @@ rules, but rather merge the minimal need-to-know elements of both, with just
 enough detail to create a prototype. A complete definition of the binary format
 and validation will be present in the [formal specification](../../spec/).
 
+See the [explainer introduction](Explainer.md) for an explanation of 🪙.
+
 
 ## Component Definitions
 
@@ -74,7 +76,7 @@ instantiatearg      ::= n:<string>  si:<sortidx>                           => (w
 sortidx             ::= sort:<sort> idx:<u32>                              => (sort idx)
 sort                ::= 0x00 cs:<core:sort>                                => core cs
                       | 0x01                                               => func
-                      | 0x02                                               => value
+                      | 0x02                                               => value 🪙
                       | 0x03                                               => type
                       | 0x04                                               => component
                       | 0x05                                               => instance
@@ -102,8 +104,8 @@ 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 each `<name>`, `<regid>` or
-  `<regidset>` in an `importname` in `c` to match a `string` in a `with`
+* Validation of `instantiate` requires each `<name>`, `<iid>`, `<pkgid>` or
+  `<pkgidset>` in an `importname` in `c` to match a `string` in a `with`
   argument and for the types to match.
 * When validating `instantiate`, after each individual type-import is supplied
   via `with`, the actual type supplied is immediately substituted for all uses
@@ -207,7 +209,7 @@ defvaltype    ::= pvt:<primvaltype>                       => pvt
                 | 0x69 i:<typeidx>                        => (own i)
                 | 0x68 i:<typeidx>                        => (borrow i)
 labelvaltype  ::= l:<label> t:<valtype>                   => l t
-case          ::= l:<label> t?:<valtype>? r?:<u32>?       => (case l t? (refines case-label[r])?)
+case          ::= l:<label> t?:<valtype>? 0x00            => (case l t?)
 <T>?          ::= 0x00                                    =>
                 | 0x01 t:<T>                              => t
 valtype       ::= i:<typeidx>                             => i
@@ -229,7 +231,7 @@ importdecl    ::= in:<importname> ed:<externdesc>         => (import in ed)
 exportdecl    ::= en:<exportname> ed:<externdesc>         => (export en ed)
 externdesc    ::= 0x00 0x11 i:<core:typeidx>              => (core module (type i))
                 | 0x01 i:<typeidx>                        => (func (type i))
-                | 0x02 t:<valtype>                        => (value t)
+                | 0x02 t:<valtype>                        => (value t) 🪙
                 | 0x03 b:<typebound>                      => (type b)
                 | 0x04 i:<typeidx>                        => (component (type i))
                 | 0x05 i:<typeidx>                        => (instance (type i))
@@ -269,9 +271,8 @@ Notes:
 * Validation of function parameter and result names, record field names,
   variant case names, flag names, and enum case names requires that the name be
   unique for the func, record, variant, flags, or enum type definition.
-* Validation of the optional `refines` clause of a variant case requires that
-  the case index is less than the current case's index (and therefore
-  cases are acyclic).
+* (The `0x00` immediate of `case` may be reinterpreted in the future as the
+  `none` case of an optional immediate.)
 
 
 ## Canonical Definitions
@@ -299,7 +300,7 @@ Notes:
   [`CanonicalABI.md`](CanonicalABI.md#canonical-definitions).
 
 
-## Start Definitions
+## 🪙 Start Definitions
 
 (See [Start Definitions](Explainer.md#start-definitions) in the explainer.)
 ```ebnf
@@ -329,15 +330,16 @@ in the explainer.)
 import      ::= in:<importname> ed:<externdesc>                      => (import in ed)
 export      ::= en:<exportname> si:<sortidx> ed?:<externdesc>?       => (export en si ed?)
 exportname  ::= 0x00 n:<name>                                        => n
-              | 0x01 ri:<regid'>                                     => (interface ri)
+              | 0x01 i:<iid'>                                        => (interface i)
+iid'        ::= len:<u32> i:<iid>                                    => "i" (if len = |i|)
 importname  ::= en:<exportname>                                      => en
               | 0x02 n:<name> s:<string> i?:<integrity'>?            => n (url s i?)
               | 0x03 n:<name> s:<string> i?:<integrity'>?            => n (relative-url s i?)
               | 0x04 n:<name> i:<integrity'>                         => n i
-              | 0x05 ri:<regid'> i?:<integrity'>?                    => (locked-dep ri i?)
-              | 0x06 ris:<regidset'>                                 => (unlocked-dep ris)
-regid'      ::= len:<u32> ri:<regid>                                 => "ri" (if len = |ri|)
-regidset'   ::= len:<u32> ris:<regidset>                             => "ris" (if len = |ris|)
+              | 0x05 p:<pkgid'> i?:<integrity'>?                     => (locked-dep p i?)
+              | 0x06 p:<pkgidset'>                                   => (unlocked-dep p)
+pkgid'      ::= len:<u32> p:<pkgid>                                  => "p" (if len = |p|)
+pkgidset'   ::= len:<u32> p:<pkgidset>                               => "p" (if len = |p|)
 integrity'  ::= len:<u32> im:<integrity-metadata>                    => (integrity "im") (if len = |im|)
 ```
 
@@ -353,11 +355,10 @@ Notes:
 * The `name` fields of `exportname` and `importname` must be unique among all
   imports and exports in the containing component definition, component type or
   instance type. (An import and export cannot use the same `name`.)
-* The `regid` and `regidset` of `importname` and `exportname` must be
+* The `iid`, `pkgid` and `pkgidset` of `importname` and `exportname` must be
   unique only among imports or exports. That is, two imports may *not*
-  have the same `regid`(`set`), but an import and export *may* have the same
-  `regid`.
-* `<regid>` and `<regidset>` refer to the grammatical productions defined in
+  have the same id, but an import and export *may* have the same id.
+* `<iid>`, `<pkgid>` and `<pkgidset>` refer to the grammatical productions defined in
   the [text format](#import-and-export-definitions).
 * `<valid semver>` is as defined by [https://semver.org](https://semver.org/)
 * `<integrity-metadata>` is as defined by the

design/mvp/Explainer.md

@@ -14,7 +14,7 @@ JavaScript runtimes. For a more user-focussed explanation, take a look at the
   * [Canonical definitions](#canonical-definitions)
     * [Canonical ABI](#canonical-built-ins)
     * [Canonical built-ins](#canonical-built-ins)
-  * [Start definitions](#start-definitions)
+  * [Start definitions](#-start-definitions)
   * [Import and export definitions](#import-and-export-definitions)
 * [Component invariants](#component-invariants)
 * [JavaScript embedding](#JavaScript-embedding)
@@ -23,6 +23,15 @@ JavaScript runtimes. For a more user-focussed explanation, take a look at the
 * [Examples](#examples)
 * [TODO](#TODO)
 
+By default, the features described in this explainer (as well as the supporting
+[Binary.md](Binary.md), [WIT.md](WIT.md) and [CanonicalABI.md](CanonicalABI.md))
+have been implemented and are included in the [WASI Preview 2] stability
+milestone. Features that are not part of Preview 2 are demarcated by one of the
+emoji symbols listed below; these emojis will be removed once they are
+implemented, considered stable and included in a future milestone:
+* 🪙: value imports/exports and component-level start function
+* 🪺: nested namespaces and packages in import/export names
+
 (Based on the previous [scoping and layering] proposal to the WebAssembly CG,
 this repo merges and supersedes the [module-linking] and [interface-types]
 proposals, pushing some of their original features into the post-MVP [future
@@ -63,7 +72,7 @@ definition ::= core-prefix(<core:module>)
              | <alias>
              | <type>
              | <canon>
-             | <start>
+             | <start> 🪺
              | <import>
              | <export>
 
@@ -197,7 +206,7 @@ instantiatearg ::= (with <string> <sortidx>)
 sortidx        ::= (<sort> <u32>)
 sort           ::= core <core:sort>
                  | func
-                 | value
+                 | value 🪙
                  | type
                  | component
                  | instance
@@ -221,7 +230,7 @@ future include `data`). Thus, component-level `sort` injects the full set
 of `core:sort`, so that they may be referenced (leaving it up to validation
 rules to throw out the core sorts that aren't allowed in various contexts).
 
-The `value` sort refers to a value that is provided and consumed during
+🪙 The `value` sort refers to a value that is provided and consumed during
 instantiation. How this works is described in the
 [start definitions](#start-definitions) section.
 
@@ -489,7 +498,7 @@ defvaltype    ::= bool
                 | float32 | float64
                 | char | string
                 | (record (field <label> <valtype>)+)
-                | (variant (case <id>? <label> <valtype>? (refines <id>)?)+)
+                | (variant (case <id>? <label> <valtype>?)+)
                 | (list <valtype>)
                 | (tuple <valtype>+)
                 | (flags <label>+)
@@ -520,7 +529,7 @@ externdesc    ::= (<sort> (type <u32>) )
                 | <functype>
                 | <componenttype>
                 | <instancetype>
-                | (value <valtype>)
+                | (value <valtype>) 🪙
                 | (type <typebound>)
 typebound     ::= (eq <typeidx>)
                 | (sub resource)
@@ -574,13 +583,6 @@ through these canonical definitions. The `typeidx` immediate of a handle type
 must refer to a `resource` type (described below) that statically classifies
 the particular kinds of resources the handle can point to.
 
-The [subtyping] between all these types is described in a separate
-[subtyping explainer](Subtyping.md). Of note here, though: the optional
-`refines` field in the `case`s of `variant`s is exclusively concerned with
-subtyping. In particular, a `variant` subtype can contain a `case` not present
-in the supertype if the subtype's `case` `refines` (directly or transitively)
-some `case` in the supertype.
-
 The sets of values allowed for the remaining *specialized value types* are
 defined by the following mapping:
 ```
@@ -649,7 +651,7 @@ references to out-of-line type definitions (via `(type <typeidx>)`) and inline
 type expressions that the text format desugars into out-of-line type
 definitions.
 
-The `value` case of `externdesc` describes a runtime value that is imported or
+🪙 The `value` case of `externdesc` describes a runtime value that is imported or
 exported at instantiation time as described in the
 [start definitions](#start-definitions) section below.
 
@@ -729,11 +731,7 @@ Like core modules, components have an up-front validation phase in which the
 definitions of a component are checked for basic consistency. Type checking
 is a central part of validation and, e.g., occurs when validating that the
 `with` arguments of an [`instantiate`](#instance-definitions) expression are
-type-compatible with the `import`s of the component being instantiated. To allow
-backwards-compatible API evolution, "compatibility" is defined in terms of a
-[subtyping] relation, saying that `t1` is "compatible" with `t2` when a value
-of type `t1` is *substitutable* for a value of `t2` without breaking any basic
-assumptions the receiver has about `t2` values.
+type-compatible with the `import`s of the component being instantiated.
 
 To incrementally describe how type-checking works, we'll start by asking how
 *type equality* works for non-resource, non-handle, local type definitions and
@@ -766,28 +764,42 @@ all 5 variations of `$ListListStringX` are considered equal since, after
 decoding, they all have the same AST.
 
 Next, the type equality relation on ASTs is relaxed to a more flexible
-subtyping relation. This subtyping relation is recursively defined starting
-with a set of base-case rules such as:
-* `u8` is a subtype of `u16`
-* `f32` is a subtype of `f64`
-
-and then a set of inductive rules like:
-* If `t1` is a subtype of `t2`, `list t1` is a subtype of `list t2`
-* If `t1` is a subtype of `t2`, `option t1` is a subtype of `option t2`
-
-The full list of rules is in [`Subtyping.md`](Subtyping.md). The rules are
-defined so that a type-checking implementation can simply recurse on the ASTs
-of two types in tandem to determine at each node whether the "left-hand side" is
-a subtype of the "right-hand side". For example, the following component is
-valid because, using the rules just given, the decoded AST of `$L1` is a
-subtype of the decoded AST of `$L2`:
-```wasm
+[subtyping] relation. Currently, subtyping is only relaxed for `instance` and
+`component` types, but may be relaxed for more type constructors in the future
+to better support API Evolution (being careful to understand how subtyping
+manifests itself in the wide variety of source languages so that
+subtype-compatible updates don't inadvertantly break source-level clients).
+
+Component and instance subtyping allows a subtype to export more and import
+less than is declared by the supertype, ignoring the exact order of imports and
+exports and considering only names. For example, here, `$I1` is a subtype of
+`$I2`:
+```wat
 (component
-  (import "v1" (value $v1 (list (list u8))))
-  (component $C
-    (import "v2" (value $v2 (list (list u16))))
-  )
-  (instance $c (instantiate $C (with "v2" (value $v1))))
+  (type $I1 (instance
+    (export "foo" (func))
+    (export "bar" (func))
+    (export "baz" (func))
+  ))
+  (type $I2 (instance
+    (export "bar" (func))
+    (export "foo" (func))
+  ))
+)
+```
+and `$C1` is a subtype of `$C2`:
+```wat
+(component
+  (type $C1 (component
+    (import "a" (func))
+    (export "x" (func))
+    (export "y" (func))
+  ))
+  (type $C2 (component
+    (import "a" (func))
+    (import "b" (func))
+    (export "x" (func))
+  ))
 )
 ```
 
@@ -1239,7 +1251,7 @@ See the [CanonicalABI.md](CanonicalABI.md#canonical-definitions) for detailed
 definitions of each of these built-ins and their interactions.
 
 
-### Start Definitions
+### 🪙 Start Definitions
 
 Like modules, components can have start functions that are called during
 instantiation. Unlike modules, components can call start functions at multiple
@@ -1306,19 +1318,22 @@ exported). The grammar for imports and exports is:
 import     ::= (import <importname> bind-id(<externdesc>))
 export     ::= (export <id>? <exportname> <sortidx> <externdesc>?)
 exportname ::= <name>
-             | (interface "<regid>")
+             | (interface "<iid>")
+iid        ::= <namespace><label><projection><version>?
+             | <namespace>+<label><projection>+<version>? 🪺
+namespace  ::= <label>:
+projection ::= /<label>
+version    ::= @<valid semver>
 importname ::= <exportname>
              | <name> (url <string> <integrity>?)
              | <name> (relative-url <string> <integrity>?)
              | <name> <integrity>
-             | (locked-dep "<regid>" <integrity>?)
-             | (unlocked-dep "<regidset>")
-regname    ::= <namespace>+<label><projection>*
-namespace  ::= <label>:
-projection ::= /<label>
-regid      ::= <regname><version>?
-regidset   ::= <regname><verrange>?
-version    ::= @<valid semver>
+             | (locked-dep "<pkgid>" <integrity>?)
+             | (unlocked-dep "<pkgidset>")
+pkgname    ::= <namespace><label>
+             | <namespace>+<label><projection>* 🪺
+pkgid      ::= <pkgname><version>?
+pkgidset   ::= <pkgname><verrange>?
 verrange   ::= <version>
              | @*
              | @{<verlower>}
@@ -1385,11 +1400,12 @@ host must locate the contents using the hash (e.g., using an [OCI Registry]).
 
 The "registry" referred to by dependency names serves to map a hierarchical
 name and version to either a component or an export of a component. For
-example, in the registry name `a:b:c/d/e/f`, `a:b:c` traverses a path
-through namespaces `a` and `b` to a component `c` and `/d/e/f` traverses the
-exports of `c` (where `d` and `e` must be component exports but `f` can be
-anything). Given this abstract definition, a number of concrete data sources
-can be interpreted by developer tooling as "registries":
+example, in the full generality of nested namespaces and packages (🪺),
+in a registry name `a:b:c/d/e/f`, `a:b:c` traverses a path through namespaces
+`a` and `b` to a component `c` and `/d/e/f` traverses the exports of `c` (where
+`d` and `e` must be component exports but `f` can be anything). Given this
+abstract definition, a number of concrete data sources can be interpreted by
+developer tooling as "registries":
 * a live registry (perhaps accessed via [`warg`])
 * a local filesystem directory (perhaps containing vendored dependencies)
 * a fixed set of host-provided functionality (see also the [built-in modules] proposal)
@@ -1415,8 +1431,8 @@ sequence of labels in a registry name can be translated to nested scopes in the
 source language, thereby leveraging existing namespacing in the registry to
 avoid conflicts in the source bindings. Note that, because of the mandatory `:`
 in registry names, the set of kebab names and registry names is disjoint and so
-no discriminant is required to distinguish between a `name` and `regname`; a
-plain `string` covers both cases.
+no discriminant is required to distinguish between a `name`, `iid` or `pkgid`;
+a plain `string` covers both cases.
 
 Components provide two options for naming exports, symmetric to the first two
 options for naming imports:
@@ -1609,7 +1625,7 @@ For example, the following component:
 ;; a.wasm
 (component
   (import "one" (func))
-  (import "two" (value string))
+  (import "two" (value string)) 🪙
   (import "three" (instance
     (export "four" (instance
       (export "five" (core module
@@ -1634,7 +1650,7 @@ could be successfully instantiated via:
 ```js
 WebAssembly.instantiateStreaming(fetch('./a.wasm'), {
   one: () => (),
-  two: "hi",
+  two: "hi", 🪙
   three: {
     four: {
       five: await WebAssembly.compileStreaming(fetch('./b.wasm'))
@@ -1878,6 +1894,7 @@ and will be added over the coming months to complete the MVP proposal:
 [stack-switching]: https://github.com/WebAssembly/stack-switching/blob/main/proposals/stack-switching/Overview.md
 [esm-integration]: https://github.com/WebAssembly/esm-integration/tree/main/proposals/esm-integration
 [gc]: https://github.com/WebAssembly/gc/blob/main/proposals/gc/MVP.md
+[WASI Preview 2]: https://github.com/WebAssembly/WASI/tree/main/preview2
 
 [Adapter Functions]: FutureFeatures.md#custom-abis-via-adapter-functions
 [Canonical ABI]: CanonicalABI.md