Add 'optional' imports/exports

Author: lukewagner

design/mvp/CanonicalABI.md

@@ -68,6 +68,7 @@ specified here.
   * [`canon thread.yield-then-resume`](#-canon-threadyield-then-resume) 🧵
   * [`canon thread.suspend-then-promote`](#-canon-threadsuspend-then-promote) 🧵
   * [`canon thread.yield-then-promote`](#-canon-threadyield-then-promote) 🧵
+  * [`canon optional.present`](#-canon-optionalpresent) ❓
   * [`canon error-context.new`](#-canon-error-contextnew) 📝
   * [`canon error-context.debug-message`](#-canon-error-contextdebug-message) 📝
   * [`canon error-context.drop`](#-canon-error-contextdrop) 📝
@@ -3579,6 +3580,10 @@ validation is performed:
 * if `len(flatten_types(ft.param_types())) > MAX_FLAT_PARAMS`, `realloc` is required
 * if `len(flatten_types(ft.result_type())) > max` (where `max = MAX_FLAT_RESULTS` for sync lifts, and `max = MAX_FLAT_PARAMS` for async lifts), `memory` is required
 
+TODO: if `$ft` is optional and one of its referenced resource types is imported and
+"none", the `canon lift`ed function becomes "none"
+TODO: define some `refers_to_non_existent_resource`, `assert(not refers_to_non_existent_resource(ft))`
+
 Note that an `async`-lifted function whose result type requires a memory to lift
 (either because it contains lists or strings or because the number of flattened
 types exceeds `MAX_FLAT_PARAMS`) must include a `memory` option, and that option
@@ -3816,10 +3821,13 @@ runtime Core WebAssembly arguments.
 Based on this, `canon_lower` is defined in chunks as follows. First, like most
 Canonical ABI functions callable from Core WebAssembly, lowered imports may not
 be called during `post-return` or `realloc`:
+TODO: mention optional
 ```python
 def canon_lower(callee, ft, opts, flat_args: list[CoreValType]) -> list[CoreValType]:
   thread = current_thread()
   trap_if(not thread.task.inst.may_leave)
+  assert(ft.optional or callee is not None)
+  trap_if(callee is None)
 ```
 
 The component-level function type maps to a Core WebAssembly function type using
@@ -5110,6 +5118,19 @@ prepared to propagate cancellation, they can omit `cancellable` so that
 cancellation is instead delivered at a later `cancellable` call.
 
 
+### ❓ `canon optional.present`
+
+For a canonical definition:
+```wat
+(canon optional.present $sortidx (core global $present))
+```
+validation specifies:
+* `$sortidx` must ... and be `optional`
+* `$present` is given type `(global i32)`
+
+TODO: describe
+
+
 ### 📝 `canon error-context.new`
 
 For a canonical definition:

design/mvp/Explainer.md

@@ -27,6 +27,7 @@ more user-focused explanation, take a look at the
     * [Canonical built-ins](#canonical-built-ins)
       * [Resource built-ins](#resource-built-ins)
       * [Concurrency built-ins](#-concurrency-built-ins)
+      * [Optionality built-ins](#-optionality-built-ins)
       * [Error Context built-ins](#-error-context-built-ins)
   * [Value definitions](#-value-definitions)
   * [Start definitions](#-start-definitions)
@@ -69,6 +70,7 @@ subsequent WASI Developer Preview minor releases:
 * 🐘: [memory64]
 * 🗺️: the `map` type
 * 🏷️: `implements` annotations for plain-named interface imports/exports
+* ❓: `optional` imports and exports
 
 
 ## Grammar
@@ -298,6 +300,7 @@ instanceexpr   ::= (instantiate <componentidx> <instantiatearg>*)
                  | <inlineexport>*
 instantiatearg ::= (with <name> <sortidx>)
                  | (with <name> (instance <inlineexport>*))
+                 | (with <name>) ❓
 name           ::= <core:name>
 sortidx        ::= (<sort> <u32>)
 sort           ::= core <core:sort>
@@ -607,9 +610,13 @@ valtype       ::= <typeidx>
 keytype       ::= bool | s8 | u8 | s16 | u16 | s32 | u32 | s64 | u64 | char | string 🗺️
 resourcetype  ::= (resource (rep i32) (dtor <core:funcidx>)?)
                 | (resource (rep i64) (dtor <core:funcidx>)?) 🐘
-functype      ::= (func async? (param <labellit> <valtype>)* (result <valtype>)?)
+functype      ::= (func <optional?> <async?> (param <labellit> <valtype>)* (result <valtype>)?)
+optional?     ::= ϵ
+                | optional ❓
+async?        ::= ϵ
+                | async 🔀
 componenttype ::= (component <componentdecl>*)
-instancetype  ::= (instance <instancedecl>*)
+instancetype  ::= (instance <optional?> <instancedecl>*)
 componentdecl ::= <importdecl>
                 | <instancedecl>
 instancedecl  ::= core-prefix(<core:type>)
@@ -626,7 +633,7 @@ externtype    ::= (<sort> (type <u32>) )
                 | (value <valuebound>) 🪙
                 | (type <typebound>)
 typebound     ::= (eq <typeidx>)
-                | (sub resource)
+                | (sub <optional?> resource)
 valuebound    ::= (eq <valueidx>) 🪙
                 | <valtype> 🪙
 
@@ -1298,6 +1305,9 @@ replaced by `$R` when validating the instantiations of `$c1` and `$c2`. These
 type-checking rules for instantiating type imports mirror the *elimination*
 rule of [universal types]  (∀T).
 
+TODO: if don't provide type, substitute incompatible type; prevent functions
+from being supplied...
+
 Importantly, this type substitution performed by the parent is not visible to
 the child at validation- or run-time. In particular, there are no runtime
 casts that can "see through" to the original type parameter, avoiding
@@ -1544,6 +1554,7 @@ canon ::= ...
         | (canon thread.yield-then-resume cancellable? (core func <id>?)) 🧵
         | (canon thread.suspend-then-promote cancellable? (core func <id>?)) 🧵
         | (canon thread.yield-then-promote cancellable? (core func <id>?)) 🧵
+        | (canon optional.present <sortidx> (core global <id>?)) ❓
         | (canon error-context.new <canonopt>* (core func <id>?)) 📝
         | (canon error-context.debug-message <canonopt>* (core func <id>?)) 📝
         | (canon error-context.drop (core func <id>?)) 📝
@@ -2330,6 +2341,13 @@ For details, see [`canon_thread_available_parallelism`] in the Canonical ABI
 explainer.
 
 
+##### ❓ Optionality built-ins
+
+###### ❓ `optional.present`
+
+TODO
+
+
 ##### 📝 Error Context built-ins
 
 ###### 📝 `error-context.new`

design/mvp/WIT.md

@@ -308,6 +308,9 @@ world union-my-world {
 }
 ```
 
+TODO: add `optional` to some of the `include` examples above (unions *both* imports and exports)
+TODO: add a note that `include` does not produce subtype or supertype, but other ways to combine worlds (`meet` and `join`) could be added in the future
+
 ### De-duplication of interfaces
 
 If two worlds share an imported or exported [interface name], then the union of
@@ -339,6 +342,8 @@ world union-my-world-b {
 }
 ```
 
+TODO: mention merging of `optional` and non-`optional` ~~> non-`optional`
+
 ### Name Conflicts and `with`
 
 When two or more included Worlds have the same name for an import or export
@@ -436,12 +441,6 @@ world invalid-union-world {
 
 ```
 
-### A Note on Subtyping
-
-In the future, when `optional` export is supported, the world author may explicitly mark exports as optional to make a component targeting an included World a subtype of the union World.
-
-For now, we are not following the subtyping rules for the `include` statement. That is, the `include` statement does not imply any subtyping relationship between the included worlds and the union world.
-
 ## WIT Packages and `use`
 [use]: #wit-packages-and-use
 
@@ -563,6 +562,8 @@ interface my-interface {
 }
 ```
 
+TODO: `use` resolution when only used from `optional`y-imported interfaces --> `optional`
+
 #### Top-level `use`
 
 If a package being referred to has a version number, then using the above syntax
@@ -1075,6 +1076,7 @@ keyword ::= 'as'
           | 'list'
           | 'map'
           | 'option'
+          | 'optional'
           | 'own'
           | 'package'
           | 'record'
@@ -1441,10 +1443,10 @@ world-definition ::= export-item
                    | typedef-item
                    | include-item
 
-export-item ::= external-id? 'export' id ':' extern-type
-              | 'export' use-path ';'
-import-item ::= external-id? 'import' id ':' extern-type
-              | 'import' use-path ';'
+export-item ::= external-id? 'export' id ':' 'optional'? extern-type
+              | 'export' 'optional'? use-path ';'
+import-item ::= external-id? 'import' id ':' 'optional'? extern-type
+              | 'import' 'optional'? use-path ';'
 
 external-id ::= '@external-id' '(' string-literal ')' 🏷️
 
@@ -1508,6 +1510,8 @@ world my-world {
 }
 ```
 
+TODO: note `optional` and what it means
+
 [`componenttype`]: Explainer.md#type-definitions
 
 ## Item: `include`