Merge pull request #155 from WebAssembly/extend-exports

add optional export type ascription

Author: lukewagner

design/mvp/Binary.md

@@ -324,10 +324,10 @@ 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>    => (export en si)
-externname ::= n:<name> u?:<URL>?              => n u?
-URL        ::= b*:vec(byte)                    => char(b)*, if char(b)* parses as a URL
+import     ::= en:<externname> ed:<externdesc>                => (import en ed)
+export     ::= en:<externname> si:<sortidx> ed?:<externdesc>? => (export en si ed?)
+externname ::= n:<name> u?:<URL>?                             => n u?
+URL        ::= b*:vec(byte)                                   => char(b)*, if char(b)* parses as a URL
 ```
 Notes:
 * All exports (of all `sort`s) introduce a new index that aliases the exported
@@ -338,7 +338,10 @@ Notes:
   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`).
+  (which disallows core sorts other than `core module`). When the optional
+  `externdesc` immediate is present, validation requires it to be equal to
+  the inferred `externdesc` of the `sortidx` (where equality judges a type and
+  the `typeidx` of an export of that type (via `eq` or `sub`) equivalent).
 * The `name` fields of `externname` must be unique among imports and exports,
   respectively. The `URL` fields of `externname` (that are present) must
   independently unique among imports and exports, respectively.

design/mvp/Explainer.md

@@ -1299,7 +1299,7 @@ of core linear memory.
 Lastly, imports and exports are defined as:
 ```
 import     ::= (import <externname> bind-id(<externdesc>))
-export     ::= (export <id>? <externname> <sortidx>)
+export     ::= (export <id>? <externname> <sortidx> <externdesc>?)
 externname ::= <name> <URL>?
 ```
 Both import and export definitions append a new element to the index space of
@@ -1313,7 +1313,11 @@ exported).
 Validation of `export` requires that all transitive uses of resource types in
 the types of exported functions or values refer to resources that were either
 imported or exported (concretely, via the type index introduced by an `import`
-or `export`). For example, in the following component:
+or `export`). The optional `<externdesc>?` in `export` can be used to ascribe
+an equivalent-but-different type to an exported definition, allowing a private
+type definition to be replaced with a public (exported) type definition.
+
+For example, in the following component:
 ```wasm
 (component
   (import "R1" (type $R1 (sub resource)))
@@ -1324,6 +1328,7 @@ or `export`). For example, in the following component:
   (func $f2' (result (own $R2')) (canon lift ...))
   (export "f1" (func $f1))
   ;; (export "f2" (func $f2)) -- invalid
+  (export "f2" (func $f2) (func (result (own $R2'))))
   (export "f2" (func $f2'))
 )
 ```