Merge pull request #51 from WebAssembly/polyfill-section

Tidy up HighLevelGoals

4 files changed, 36 insertions, 29 deletions

diff --git a/AstSemantics.md b/AstSemantics.md
index 2a47924..96ab81c 100644
--- a/AstSemantics.md
+++ b/AstSemantics.md
@@ -104,9 +104,8 @@ heap accesses in asm.js force alignment (e.g., `HEAP32[i>>2]` masks off the
 low two bits), the asm.js polyfill would need to translate *all* loads/stores
 into byte accesses (regardless of specified alignment) to be correct. However,
 to achieve competitive performance, the polyfill defaults to incorrect behavior
-by emitting full-size accesses as if the index was never misaligned. This 
-follows from the [high-level goals](HighLevelGoals.md). Thus, code generators
-have *two* strong reasons to always emit accurate alignment.
+by emitting full-size accesses as if the index was never misaligned. Thus, code
+generators have *two* strong reasons to always emit accurate alignment.
 
 Either tooling or an explicit opt-in "debug mode" in the spec should allow
 execution of a module in a mode that threw exceptions on misaligned access.
diff --git a/BinaryEncoding.md b/BinaryEncoding.md
index 34e106b..8a9d9d1 100644
--- a/BinaryEncoding.md
+++ b/BinaryEncoding.md
@@ -83,10 +83,6 @@ as a starting point for defining a real standard binary format.*
 
 ## Backwards Compatibility
 
-Restating the relevant [high-level goal](HighLevelGoals.md): "Design to maintain the versionless, 
-feature-testing and backwards-compatible evolution story of the web; engines should not need 
-multiple, versioned decoders".
-
 As explained above, for size- and decode-efficiency, the binary format will serialize AST nodes,
 their contents and children using dense integer indices and without any kind of embedded metadata 
 or tagging. This raises the question of how to reconcile the efficient encoding with the 
diff --git a/HighLevelGoals.md b/HighLevelGoals.md
index 7da0870..503aec1 100644
--- a/HighLevelGoals.md
+++ b/HighLevelGoals.md
@@ -1,30 +1,28 @@
 # WebAssembly High-Level Goals
 
 1. Define a portable, size- and load-time-efficient binary format to serve as a
-   web compilation target which can be compiled to execute at native speed by
-   taking advantage of common hardware capabilities.
-2. Define a human-editable text format that is isomorphic and convertible
-   to/from the binary format.
-3. Design to serve as a compilation target for a growing set of source languages
-   over time, starting with C/C++.
-4. Design to maintain the versionless, feature-testing and 
-   [backwards-compatible](BinaryEncoding.md#backwards-compatibility) evolution story of the web; 
-   engines should not need multiple, versioned decoders.
-5. Design and implement incrementally:
-    * [v.1](V1.md) of the standard will be a Minimum Viable Product with a [polyfill][] via client-side compilation to [asm.js][] and thus run on existing browsers.
-      In semantic corner cases (such as out-of-bounds and alignment, which evoke Undefined Behavior in C and C++), where asm.js does not have ideal semantics,
-      the default polyfill would diverge for performance reasons (it would also be possible to run a more precise but slower polyfill, but almost all
-      real-world applications are not expected to need to do so).
-    * subsequent versions will add more [features](EssentialPostV1Features.md) prioritized by feedback. Some of those features might not be polyfillable
-      to asm.js in a practical way.
-6. Design to execute within and integrate well with the existing web platform:
+   compilation target which can be compiled to execute at native speed by taking
+   advantage of common hardware capabilities.
+2. Define a human-editable text format that is convertible to and from the binary
+   format.
+3. Specify and implement incrementally:
+    * Design [v.1](V1.md) of the standard as a Minimum Viable Product with roughly
+      the same functionality as [asm.js](http://asmjs.org).
+    * Plan to iteratively specify [additional](EssentialPostV1Features.md)
+      [features](FutureFeatures.md) after v.1.
+    * Plan to iteratively improve support for compilation from languages other
+      than C/C++ (e.g., languages with [GC](FutureFeatures.md#gcdom-integration)).
+4. Ship an effective [polyfill](V1.md#polyfill) library for v.1 that translates
+   WebAssembly code into asm.js in the client so that WebAssembly can run on
+   existing browsers at high speeds.
+5. Design to execute within and integrate well with the *existing* web platform:
+    * maintain the versionless, feature-tested and 
+      [backwards-compatible](BinaryEncoding.md#backwards-compatibility) evolution
+      story of the web;
     * execute in the same semantic universe as JavaScript;
     * allow synchronous calls to and from JavaScript;
     * enforce the same-origin and permissions security policies; and
     * access browser functionality through the same Web APIs that are accessible
       to JavaScript.
-7. Design to allow execution in non-browser environments.
-8. Create a format which enables great [tooling](Tooling.md) people want to use.
-
-  [polyfill]: https://github.com/WebAssembly/polyfill
-  [asm.js]: http://asmjs.org
+6. Design to allow execution in non-browser environments.
+7. Enable great [tooling](Tooling.md).
diff --git a/V1.md b/V1.md
index b559d55..d0c5dbe 100644
--- a/V1.md
+++ b/V1.md
@@ -104,6 +104,20 @@ precise descriptions of:
    * To keep an ArrayBuffer's length immutable, resizing a module's heap detaches any existent ArrayBuffers.
  * See the [AST Semantics heap section](AstSemantics.md#accessing-the-heap) for
    more details.
+
+## Polyfill
+ * A working prototype is in the [polyfill repo](https://github.com/WebAssembly/polyfill).
+ * Even before browsers ship native support for WebAssembly, users can derive
+   value from the polyfill due to the decreased download size of the
+   [binary encoding](BinaryEncoding.md) and minimal impact on startup performance.
+ * A polyfill doesn't need to be 100% correct w.r.t the specficiation to be
+   useful in practice. In the corner cases of [heap access](AstSemantics.md#accessing-the-heap)
+   which fall into Undefined Behavior in C/C++ (out-of-bounds and misaligned
+   access), asm.js does not have ideal semantics. To maintain good polyfill
+   performance, the polyfill library will diverge from the specified WebAssembly semantics.
+   * If needed, the polyfill could provide an option to ensure full correctness
+     at the expense of performance, though this is not expected to be necessary
+     for portable C/C++ code.
  
 ## Non-browser embedding
  * Host environments can define builtin modules that are implemented natively and thus be imported