Update README.md and other docs based on WASI 0.3 release

Author: lukewagner

README.md

@@ -1,31 +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 as part of [WASI]
-"Developer Preview" releases. The features enabled by default in a Developer
-Preview release are kept stable so that they can be used outside the browser in
-production settings to collect feedback that informs subsequent iterations
-leading up to the standard 1.0 release.
+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
+read-world feedback.
 
-The current Developer Releases are:
-* 0.2: the initial release including ...
-* 0.3: adding ...
+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: adds native [concurrency] support to the Component Model and [WIT];
+         includes `async` functions, `stream`s and `future`s as well as new
+         [ABI] built-in functions; additions are marked by the 🔀 emoji
+         throughout the repo.
 
-The subsequent [WASI Preview 3] milestone will be
-primarily concerned with the addition of [async and thread support][Concurrency
-Model].
+Subsequent WASI Developer Preview releases will include other emoji-[gated
+features] such as cooperative threads (🧵).
 
 ## Contributing
 
@@ -39,12 +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]: 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)
@@ -35,8 +35,8 @@ 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:
+[use cases](../high-level/UseCases.md), with the release of [WASI] 0.3, the
+following concurrency-specific goals and use cases are added:
 
 * 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 just like 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.
@@ -1463,7 +1464,7 @@ 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
+release of [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
@@ -1496,8 +1497,7 @@ the whole tree would be kept alive.
 
 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:
+concurency 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

@@ -53,9 +53,9 @@ 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
+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) release:
+WASI Developer Preview minor releases:
 * 🪙: value imports/exports and component-level start function
 * 🪺: nested namespaces and packages in import/export names
 * 🚝: enabling more canonical ABI options on more async-related builtins

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