Update README.md and other docs based on WASI 0.3 release (#667)

Author: lukewagner

README.md

@@ -1,22 +1,35 @@
 # Component Model design and specification
 
-This repository is where the component model is being standardized. For a more
+This repository is where the Component Model is being standardized. For a more
 user-focused explanation, take a look at the **[Component Model Documentation]**.
 
-This repository contains the high-level [goals], [use cases], [design choices]
-and [FAQ] of the Component Model as well as more-detailed, low-level explainer
-docs describing the [IDL], [text format], [binary format], [concurrency model]
-and [Canonical ABI].
+This repository contains:
+* high-level [goals], [use cases], [design choices] and [FAQ] docs
+* low-level [WIT], [text format], [binary format], [concurrency] and [ABI] docs
+* a growing [WAST test suite]
 
-In the future, this repository will additionally contain a [formal spec],
-reference interpreter and test suite.
+In the future, this repository will additionally contain a [formal spec] and a
+reference interpreter.
 
 ## Milestones
 
-The Component Model is currently being incrementally developed and stabilized
-as part of [WASI Preview 2]. The subsequent [WASI Preview 3] milestone will be
-primarily concerned with the addition of [async and thread support][Concurrency
-Model].
+The Component Model is currently being developed incrementally as part of [WASI]
+"Developer Preview" releases. The Component Model features enabled as part of a
+WASI Developer Preview release are kept stable by producer and consumer tools so
+that they can be used outside the browser in production settings to collect
+real-world feedback.
+
+The current WASI Developer Preview releases are:
+* 0.2.0: the first release based on the Component Model; includes
+         shared-nothing and shared-everything [linking], a variety of high-level
+         value types, `resource` types with handles, and [WIT].
+* 0.3.0: the first release with native [concurrency] support in the Component
+         Model and [WIT]; adds `async` functions, `stream`s and `future`s as
+         well as new [ABI] built-in functions (additions are marked by the 🔀
+         emoji throughout the repo).
+
+Subsequent WASI Developer Preview releases will include other emoji-[gated
+features] such as cooperative threads (🧵).
 
 ## Contributing
 
@@ -30,13 +43,15 @@ To contribute to any of these repositories, see the Community Group's
 [Use Cases]: design/high-level/UseCases.md
 [Design Choices]: design/high-level/Choices.md
 [FAQ]: design/high-level/FAQ.md
-[IDL]: design/mvp/WIT.md
+[WIT]: design/mvp/WIT.md
 [Text Format]: design/mvp/Explainer.md
 [Binary Format]: design/mvp/Binary.md
-[Concurrency Model]: design/mvp/Concurrency.md
-[Canonical ABI]: design/mvp/CanonicalABI.md
+[Concurrency]: design/mvp/Concurrency.md
+[ABI]: design/mvp/CanonicalABI.md
+[WAST test suite]: test/
 [formal spec]: spec/
+[Linking]: design/mvp/Linking.md
+[Gated Features]: design/mvp/Explainer.md#gated-features
 [W3C WebAssembly Community Group]: https://www.w3.org/community/webassembly/
 [Contributing Guidelines]: https://webassembly.org/community/contributing/
-[WASI Preview 2]: https://github.com/WebAssembly/WASI/blob/main/docs/Preview2.md
-[WASI Preview 3]: https://github.com/WebAssembly/WASI/blob/main/docs/Preview2.md#looking-forward-to-preview-3
+[WASI]: https://github.com/WebAssembly/WASI

design/mvp/Concurrency.md

@@ -1,9 +1,9 @@
 # Concurrency Explainer
 
-This document contains a high-level summary of the native concurrency support
-added as part of [WASI Preview 3], providing background for understanding the
-definitions in the [WIT], [AST explainer], [binary format] and [Canonical ABI
-explainer] documents that are gated by the 🔀 (async) and 🧵 (threading) emojis.
+This document contains a high-level summary of the native concurrency support,
+providing background for understanding the definitions in the [WIT], [AST
+explainer], [binary format] and [Canonical ABI explainer] documents that are
+gated by the 🔀 (async) and 🧵 (threading) emojis.
 
 * [Goals](#goals)
 * [Summary](#summary)
@@ -34,9 +34,9 @@ explainer] documents that are gated by the 🔀 (async) and 🧵 (threading) emo
 
 ## Goals
 
-Refining the Component Model's high-level [goals](../high-level/Goals.md) and
-[use cases](../high-level/UseCases.md), [WASI Preview 3] adds the following
-concurrency-specific goals and use cases:
+With the release of [WASI] 0.3, the following concurrency-specific goals and
+use cases are added, refining the Component Model's high-level
+[goals](../high-level/Goals.md) and [use cases](../high-level/UseCases.md):
 
 * Integrate with idiomatic source-language concurrency features including:
   * `async` functions in languages like C#, JS, Python, Rust and Swift
@@ -92,7 +92,7 @@ invariant is necessary to allow non-`async` component exports to be called in
 synchronous contexts (like event listeners, callbacks, getters, setters and
 constructors).
 
-The new async ABI can be used alongside or instead of the existing Preview 2
+The new async ABI can be used alongside or instead of the existing [WASI] 0.2
 "sync ABI" to call or implement any `async`-typed functions. When *calling* an
 imported function via the async ABI, if the `async` callee [blocks](#blocking),
 control flow is returned immediately to the caller, and the callee continues
@@ -108,7 +108,7 @@ can compile directly to components exporting `async` functions without having
 to be rewritten to use source-language concurrency mechanisms (like callbacks,
 `async`/`wait`, coroutines, etc). For example, traditional C programs with a
 `main()` and calls to `read()`, `write()` and `select()` can run without change
-in the Preview 3 `wasi:cli/command` world, which exports `run: async func() ->
+in the [WASI] 0.3 `wasi:cli/command` world, which exports `run: async func() ->
 result`. Thus, `async` in WIT does not require the same kind of transitive
 source-code changes as source-level `async` in languages like C#, Python, JS,
 Rust and Dart.
@@ -911,9 +911,10 @@ the Component Model has [Component Invariant] #2. This is enforced by the
 [Canonical ABI](CanonicalABI.md#embedding) using strategically placed traps and
 boolean flags on component instances.
 
-With Preview 3, a desirable outcome is that if our component imports `imp` and
-exports `exp` as `async` functions, then the following JS code could run the
-two `exp` calls concurrently just like if they were JS `async` functions:
+With native concurrency support, what we'd naturally expect is that if our
+component imports `imp` and exports `exp` as `async` functions, then the
+following JS code could run the two `exp` calls concurrently, as if they were JS
+`async` functions:
 ```js
 import source component from './component.wasm';
 async function imp() {
@@ -1003,7 +1004,7 @@ task" to which work can be dispatched (e.g., via the `setInterval()` or
 concurrency], these background tasks are new task tree roots (siblings to the
 roots created when component exports are called by the host).
 
-As a Preview 3 follow-up [TODO](#TODO), component type definitions should be
+As a post-0.3.0 follow-up [TODO](#TODO), component type definitions should be
 extended to allow an `async` effect that declares that component instantiation
 is allowed to [block](#blocking). This would be necessary to implement, e.g.,
 JS [top-level `await`] or I/O in C++ constructors executing during `start`.
@@ -1013,7 +1014,7 @@ JS [top-level `await`] or I/O in C++ constructors executing during `start`.
 
 At an ABI level, native async in the Component Model defines for every
 `async`-typed function a non-blocking core function signature that can be
-used instead of or in addition to the existing (Preview-2-defined) synchronous
+used instead of or in addition to the existing ([WASI] 0.2) synchronous
 core function signature. This non-blocking core function signature is intended
 to be called or implemented by generated bindings which then map the low-level
 core async protocol to the languages' higher-level native concurrency features.
@@ -1406,7 +1407,7 @@ instance lifetimes are flexible in this manner and don't have an obvious end
 conventionally ends right after `main()` returns), the host still needs to
 understand the expectations of component authors to enable portability.
 
-Before the addition of native concurrency support in Preview 3, a natural
+Before the addition of native concurrency support in [WASI] 0.3, a natural
 expectation is that, in the absence of atypical scenarios like timeouts or quota
 exhaustion, a component author can expect that their component instance will not
 be abruptly terminated during the execution of contained Core WebAssembly code.
@@ -1462,16 +1463,16 @@ waiting on `async` operations to complete.
 
 To resolve this tension, threads are implicitly distinguished by a "keep-alive"
 flag that determines whether the expectation is that the existence of the thread
-is intended to keep the containing component instance alive. In the initial
-release of Preview 3, this "keep-alive" flag is default *set* for the [implicit
-thread](#summary) created for a task and default *cleared* for the explicit
-threads created by `thread.new-indirect`. In particular, this means that an
+is intended to keep the containing component instance alive. In [WASI] 0.3,
+this "keep-alive" flag is default *set* for the [implicit thread](#summary)
+created for a task and default *cleared* for the explicit threads created by
+`thread.new-indirect`. In particular, this means that an
 `async callback`-lifted function will keep its containing component instance
 alive until it returns the `EXIT` code (`0`).
 
 As an example, in JavaScript, the Service Worker API's [`waitUntil`] method
-would delay returning the `EXIT` code. In the initial 0.3.0 release without
-cooperative threads (🧵), [`setInterval`] would also unfortunately delay
+would delay returning the `EXIT` code. In 0.3.0, without cooperative threads
+(🧵), [`setInterval`] would also unfortunately delay
 returning the `EXIT` code and thus, without guest code intervention, would keep
 component instances alive until timeout limits were hit. The release of
 cooperative threads would offer a solution to this problem, but an awkward one.
@@ -1494,10 +1495,9 @@ the whole tree would be kept alive.
 
 ## TODO
 
-Native async support is being proposed incrementally. The following features
-will be added in future chunks roughly in the order listed to complete the full
-"async" story, with a TBD cutoff between what's in [WASI Preview 3] and what
-comes after:
+Native async support is being added incrementally. Beyond what's currently
+specified, the following features are being considered for addition to complete
+the concurrency story:
 * remove the temporary trap mentioned above that occurs when a `read` and
   `write` of a stream/future happen from within the same component instance
 * zero-copy forwarding/splicing
@@ -1613,7 +1613,7 @@ comes after:
 [wasm-gc]: https://github.com/WebAssembly/gc/blob/main/proposals/gc/MVP.md
 [wasi-libc]: https://github.com/WebAssembly/wasi-libc
 
-[WASI Preview 3]: https://github.com/WebAssembly/WASI/tree/main/wasip2#looking-forward-to-preview-3
+[WASI]: https://github.com/WebAssembly/WASI
 [Runtime Instantiation]: https://github.com/WebAssembly/component-model/issues/423
 
 [Top-level `await`]: https://github.com/tc39/proposal-top-level-await

design/mvp/Explainer.md

@@ -39,19 +39,27 @@ more user-focused explanation, take a look at the
   * [ESM-integration](#ESM-integration)
 * [Examples](#examples)
 
+(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
+feature](FutureFeatures.md) backlog.)
+
+
 ## Gated Features
 
 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:
+have been implemented and are included in the [WASI] 0.2 Developer Preview
+release. The WASI 0.3 Developer Preview release additionally includes the
+features gated by 🔀.
+
+The other features, in various stages of implementation, polish and release,
+are gated by the following emojis and, when ready, may be included in
+subsequent WASI Developer Preview minor releases:
 * 🪙: value imports/exports and component-level start function
 * 🪺: nested namespaces and packages in import/export names
-* 🔀: async
-  * 🚝: enabling more canonical ABI options on more async-related builtins
-  * 🚟: using `async` with `canon lift` without `callback` (stackful lift)
+* 🚝: enabling more canonical ABI options on more async-related builtins
+* 🚟: using `async` with `canon lift` without `callback` (stackful lift)
 * 🧵: threading built-ins
   * 🧵②: [shared-everything-threads]-based threading built-ins
 * 🔧: fixed-length lists
@@ -61,11 +69,6 @@ implemented, considered stable and included in a future milestone:
 * 🗺️: the `map` type
 * 🏷️: `implements` annotations for plain-named interface imports/exports
 
-(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
-feature](FutureFeatures.md) backlog.)
-
 
 ## Grammar
 
@@ -2945,7 +2948,7 @@ have a `canonversion`, and the concatenation of the `canonversion` and
 For compatibility with older versions of this spec, non-canonical
 `interfacename`s (with `interfaceversion`s matching any `valid semver`) are
 temporarily permitted. These non-canonical names may trigger warnings and will
-start being rejected some time after after [WASI Preview 3] is released.
+be rejected at some point in the future.
 
 
 ## Component Invariants
@@ -3319,8 +3322,7 @@ For some use-case-focused, worked examples, see:
 [memory64]: https://github.com/webAssembly/memory64
 [`rectype`]: https://webassembly.github.io/gc/core/text/types.html#text-rectype
 [shared-everything-threads]: https://github.com/WebAssembly/shared-everything-threads
-[WASI Preview 2]: https://github.com/WebAssembly/WASI/tree/main/wasip2#readme
-[WASI Preview 3]: https://github.com/WebAssembly/WASI/tree/main/wasip2#looking-forward-to-preview-3
+[WASI]: https://github.com/WebAssembly/WASI
 [reference types]: https://github.com/WebAssembly/reference-types/blob/master/proposals/reference-types/Overview.md
 [GC ABI Option]: https://github.com/WebAssembly/component-model/issues/525
 

design/mvp/Linking.md

@@ -290,7 +290,7 @@ address this use case *above* the Component Model, using an interface defined
 in [WIT] and allowing different platforms and applications to tailor the
 interface to their needs.
 
-For example, using the Preview 2 feature set of Component Model, a simple
+For example, using the current feature set of the Component Model, a simple
 dynamic plugin interface might look like the following:
 ```wit
 interface plugin-loader {
@@ -314,7 +314,7 @@ plugins (e.g., on upload to the store or registry) into a native shared object
 or DLL that can be efficiently loaded at runtime.
 
 (There are a number of ways to improve upon this basic design with additional
-post-Preview 2 features of WIT and the Component Model.)
+future features of WIT and the Component Model.)
 
 
 [Canonical ABI]: CanonicalABI.md

design/mvp/WIT.md

@@ -1,4 +1,4 @@
-# The `wit` format
+# The WIT text format
 
 The Wasm Interface Type (WIT) format is an [IDL] to provide tooling for the
 [WebAssembly Component Model][components] in two primary ways: