Merge pull request WebAssembly#51 from dhil/wasmfx-merge

Merge with WebAssembly/spec

.github/workflows/ci-interpreter.yml

@@ -17,15 +17,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Setup OCaml
-        uses: ocaml/setup-ocaml@v2
+        uses: ocaml/setup-ocaml@v3
         with:
           ocaml-compiler: 4.14.x
       - name: Setup OCaml tools
         run: opam install --yes ocamlfind.1.9.5 js_of_ocaml.4.0.0 js_of_ocaml-ppx.4.0.0
       - name: Setup Node.js
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
           node-version: 20.x
       - name: Build interpreter

.github/workflows/ci-spec.yml

@@ -17,11 +17,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
         with:
           submodules: "recursive"
       - name: Setup Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: 16
       - name: Setup Bikeshed
@@ -44,7 +44,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Setup Bikeshed
         run: pip install bikeshed && bikeshed update
       - name: Run Bikeshed
@@ -59,7 +59,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Setup Bikeshed
         run: pip install bikeshed && bikeshed update
       - name: Run Bikeshed
@@ -128,7 +128,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:
@@ -147,7 +147,7 @@ jobs:
       - build-spec-versions
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Create output directory
         run: mkdir _output && cp document/index.html _output/index.html
       - name: Download core spec artifact
@@ -187,7 +187,7 @@ jobs:
           path: _output/versions
       - name: Publish to GitHub Pages
         if: github.ref == 'refs/heads/main'
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           publish_dir: ./_output
           github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/w3c-publish.yml

@@ -1,9 +1,11 @@
-name: Publish to W3C TR space
+name: Validate/Publish to W3C TR space
 
 on:
   push:
     branches: [ main ]
     paths: [ .github/**, document/** ]
+  pull_request:
+    paths: [ .github/**, document/** ]
 
   # Allows you to run this workflow manually from the Actions tab, gh CLI tool,
   # or REST API. THe w3c-status options correspond to the valid options for
@@ -23,30 +25,45 @@ on:
           - CRD
           - CR
 
+env:
+  YARN_ENABLE_IMMUTABLE_INSTALLS: false
+  W3C_STATUS: ${{ github.event_name == 'workflow_dispatch' && inputs.w3c-status || 'WD' }}
+
 jobs:
   publish-to-w3c-TR:
-    if: github.repository == 'WebAssembly/spec'
+    strategy:
+      fail-fast: false
+      matrix:
+        spec: [core, js-api, web-api]
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
         with:
           submodules: "recursive"
       - name: Setup Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: 16
       - name: Setup Bikeshed
         run: pip install bikeshed && bikeshed update
       - name: Setup TexLive
+        if: ${{ matrix.spec == 'core' }}
         run: sudo apt-get update -y && sudo apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
       - name: Setup Sphinx
+        if: ${{ matrix.spec == 'core' }}
         run: pip install six && pip install sphinx==5.1.0
-      - name: Publish all specs to their https://www.w3.org/TR/ URLs
-        run: cd document && make -e WD-echidna-CI
+      - name: Publish ${{ matrix.spec }} spec to its https://www.w3.org/TR/ URL
+        if: env.W3C_ECHIDNA_TOKEN_CORE
+        run: cd document && make -e -C ${{ matrix.spec }} WD-echidna-CI
         env:
-          W3C_STATUS: ${{ github.event_name == 'push' && 'CRD' || inputs.w3c-status }}
           W3C_ECHIDNA_TOKEN_CORE: ${{ secrets.W3C_ECHIDNA_TOKEN_CORE }}
           W3C_ECHIDNA_TOKEN_JSAPI: ${{ secrets.W3C_ECHIDNA_TOKEN_JSAPI }}
           W3C_ECHIDNA_TOKEN_WEBAPI: ${{ secrets.W3C_ECHIDNA_TOKEN_WEBAPI }}
-          YARN_ENABLE_IMMUTABLE_INSTALLS: false
+          ECHIDNA_DRYRUN: ${{ !(github.event_name == 'push' && github.repository == 'WebAssembly/spec' && github.ref == 'refs/heads/main') }}
+      - name: Validate ${{ matrix.spec }} spec with Echidna
+        if: env.W3C_USERNAME
+        run: cd document && make -e -C ${{ matrix.spec }} WD-echidna
+        env:
+          W3C_USERNAME: ${{ secrets.W3C_USERNAME }}
+          W3C_PASSWORD: ${{ secrets.W3C_PASSWORD }}

document/core/Makefile

@@ -13,6 +13,7 @@ NAME          = WebAssembly
 DECISION_URL  = https://github.com/WebAssembly/meetings/blob/main/main/2024/WG-06-12.md
 TAR           = tar
 DEADLINE      = $(shell date -d "+30 days" +%Y-%m-%d 2>/dev/null || date -v +30d +%Y-%m-%d)
+ECHIDNA_DRYRUN = true
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -196,9 +197,11 @@ WD-echidna: WD-tar
 	curl 'https://labs.w3.org/echidna/api/request' \
 		--user '$(W3C_USERNAME):$(W3C_PASSWORD)' \
 		-F "tar=@$(BUILDDIR)/WD.tar" \
-		-F "decision=$(DECISION_URL)" | tee $(BUILDDIR)/WD-echidna-id.txt
+		-F "decision=$(DECISION_URL)" \
+		-F "dry-run=$(ECHIDNA_DRYRUN)" | tee $(BUILDDIR)/WD-echidna-id.txt
+	python3 ../util/check-echidna-status.py $(BUILDDIR)
 	@echo
-	@echo "Published $(W3C_STATUS). Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"
+	@echo "Uploaded $(W3C_STATUS). Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"
 
 .PHONY: WD-echidna-CI
 WD-echidna-CI: WD-tar
@@ -210,9 +213,11 @@ WD-echidna-CI: WD-tar
 	curl 'https://labs.w3.org/echidna/api/request' \
 		-F "tar=@$(BUILDDIR)/WD.tar" \
 		-F "token=$(W3C_ECHIDNA_TOKEN_CORE)" \
-		-F "decision=$(DECISION_URL)" | tee $(BUILDDIR)/WD-echidna-id.txt
+		-F "decision=$(DECISION_URL)" \
+		-F "dry-run=$(ECHIDNA_DRYRUN)" | tee $(BUILDDIR)/WD-echidna-id.txt
+	python3 ../util/check-echidna-status.py $(BUILDDIR)
 	@echo
-	@echo "Published $(W3C_STATUS). Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"
+	@echo "Uploaded $(W3C_STATUS). Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"
 
 .PHONY: diff
 diff: bikeshed

document/core/util/bikeshed_fixup.py

@@ -12,11 +12,7 @@
 def Main():
   data = open(sys.argv[1]).read()
 
-  # Make bikeshed happy
-  # Apparently it can't handle empty line before DOCTYPE comment
-  data = data.replace('\n<!DOCTYPE', '<!DOCTYPE')
-  # Ensure newline before <pre>
-  data = data.replace('<pre>', '\n<pre>')
+  # Clean up the input for Bikeshed
 
   # Don't add more than 3 levels to TOC.
   data = data.replace('<h5>', '<h5 class="no-toc">')
@@ -34,7 +30,7 @@ def Main():
       'Validation Algorithm',
       'Custom Sections',
       'Soundness',
-      'Changes',
+      'Change History',
       'Index of Types',
       'Index of Instructions',
       'Index of Semantic Rules']:
@@ -43,18 +39,6 @@ def Main():
         '<h3>A.' + str(number) + ' ' + section + '</h3>')
     number += 1
 
-
-  # Drop spurious navigation.
-  data = data.replace(
-"""
-    <div class="related" role="navigation" aria-label="related navigation">
-      <h3>Navigation</h3>
-      <ul>
-        <li class="nav-item nav-item-0"><a href="#">WebAssembly 1.1</a> &#187;</li>
-        <li class="nav-item nav-item-this"><a href="">WebAssembly 1.1</a></li> 
-      </ul>
-    </div>  """, '')
-
   # Use bikeshed biblio references for unicode and IEEE754
   data = data.replace(
       """<a class="reference external" href="https://www.unicode.org/versions/latest/">Unicode</a>""",
@@ -88,6 +72,9 @@ def Main():
                 r'\1',
                 data, flags=re.DOTALL)
 
+  # Escape some latex sequences that Bikeshed interprets as macros
+  data = data.replace(r' \\[1ex]', r' \&#x5c;\[1ex]')
+
   sys.stdout.write(data)
 
 Main()

document/js-api/Makefile

@@ -6,6 +6,7 @@ NAME          = WebAssembly
 DECISION_URL  = https://github.com/WebAssembly/meetings/blob/main/main/2024/WG-06-12.md
 TAR           = tar
 DEADLINE      = $(shell date -d "+30 days" +%Y-%m-%d 2>/dev/null || date -v +30d +%Y-%m-%d)
+ECHIDNA_DRYRUN = true
 
 .PHONY: all
 all:
@@ -35,7 +36,6 @@ diff: all
 # macOS tar has no “--transform” option (only GNU tar does), so on macOS,
 # do “brew install tar” & run “make” like this: “TAR=gtar make -e WD-tar”
 WD-tar: all
-	bikeshed spec --md-status=$(W3C_STATUS) --md-deadline=$(DEADLINE) index.bs $(BUILDDIR)/html/index.html
 	$(TAR) -C $(BUILDDIR)/html --transform="s/index.html/Overview.html/" -cf $(BUILDDIR)/WD.tar index.html
 	@echo "Built $(BUILDDIR)/WD.tar."
 
@@ -50,7 +50,11 @@ WD-echidna: WD-tar
 	curl 'https://labs.w3.org/echidna/api/request' \
 		--user '$(W3C_USERNAME):$(W3C_PASSWORD)' \
 		-F "tar=@$(BUILDDIR)/WD.tar" \
-		-F "decision=$(DECISION_URL)" | tee $(BUILDDIR)/WD-echidna-id.txt
+		-F "decision=$(DECISION_URL)" \
+		-F "dry-run=$(ECHIDNA_DRYRUN)" | tee $(BUILDDIR)/WD-echidna-id.txt
+	python3 ../util/check-echidna-status.py $(BUILDDIR)
+	@echo
+	@echo "Uploaded $(W3C_STATUS). Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"
 
 .PHONY: WD-echidna-CI
 WD-echidna-CI: WD-tar
@@ -62,6 +66,8 @@ WD-echidna-CI: WD-tar
 	curl 'https://labs.w3.org/echidna/api/request' \
 		-F "tar=@$(BUILDDIR)/WD.tar" \
 		-F "token=$(W3C_ECHIDNA_TOKEN_JSAPI)" \
-		-F "decision=$(DECISION_URL)" | tee $(BUILDDIR)/WD-echidna-id.txt
+		-F "decision=$(DECISION_URL)" \
+		-F "dry-run=$(ECHIDNA_DRYRUN)" | tee $(BUILDDIR)/WD-echidna-id.txt
+	python3 ../util/check-echidna-status.py $(BUILDDIR)
 	@echo
-	@echo "Published $(W3C_STATUS). Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"
+	@echo "Uploaded $(W3C_STATUS). Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"

document/js-api/index.bs

@@ -23,6 +23,12 @@ Date: now
     "title": "WebAssembly Core Specification",
     "publisher": "W3C WebAssembly Community Group",
     "status": "Draft"
+  },
+  "WASMWEB": {
+    "href": "https://webassembly.github.io/spec/js-api/",
+    "title": "WebAssembly Web API Specification",
+    "publisher": "W3C WebAssembly Community Group",
+    "status": "Draft"
   }
 }
 </pre>
@@ -63,10 +69,17 @@ urlPrefix: https://tc39.github.io/ecma262/; spec: ECMASCRIPT
         text: 𝔽; url: #𝔽
         text: ℤ; url: #ℤ
         text: SameValue; url: sec-samevalue
+        text: Array; url: sec-array-exotic-objects
+        text: BigInt; url: sec-ecmascript-language-types-bigint-type
 urlPrefix: https://webassembly.github.io/spec/core/; spec: WebAssembly; type: dfn
+    text: embedding interface; url: appending/embedding.html
+    text: scope; url: intro/introduction.html#scope
     url: valid/modules.html#valid-module
         text: valid
         text: WebAssembly module validation
+    text: valid limits; url: valid/types.html#valid-limits
+    text: valid memtype; url: valid/types.html#valid-memtype
+    text: valid tabletype; url: valid/types.html#valid-tabletype
     text: module grammar; url: binary/modules.html#binary-module
     text: custom section; url: binary/modules.html#custom-section
     text: customsec; url: binary/modules.html#binary-customsec
@@ -122,9 +135,11 @@ urlPrefix: https://webassembly.github.io/spec/core/; spec: WebAssembly; type: df
     text: match_valtype; url: appendix/embedding.html#embed-match-valtype
     text: error; url: appendix/embedding.html#embed-error
     text: store; url: exec/runtime.html#syntax-store
+    text: limits; url: syntax/types.html#syntax-limits
     text: table type; url: syntax/types.html#syntax-tabletype
     text: table address; url: exec/runtime.html#syntax-tableaddr
     text: function address; url: exec/runtime.html#syntax-funcaddr
+    text: memory type; url: syntax/types.html#syntax-memtype
     text: memory address; url: exec/runtime.html#syntax-memaddr
     text: global address; url: exec/runtime.html#syntax-globaladdr
     text: tag address; url: exec/runtime.html#syntax-tagaddr
@@ -226,7 +241,14 @@ emu-const {
 }
 </style>
 
-This API provides a way to access WebAssembly [[WEBASSEMBLY]] through a bridge to explicitly construct modules from JavaScript [[ECMASCRIPT]].
+<h2 id="intro">Introduction</h2>
+
+By design, the [=scope=] of the WebAssembly core specification [[WEBASSEMBLY]] does not include a description of how WebAssembly programs interact with their surrounding execution environment.
+Instead it defines an abstract [=embedding interface=] between WebAssembly and its environment, (called the *embedder*).
+It is only through this interface that an embedder interacts with the semantics of WebAssembly, and the embedder implements the connection between its host environment and the embedding API.
+This document describes the embedding of WebAssembly into JavaScript [[ECMASCRIPT]] environments, including how WebAssembly modules can be constructed and instantiated, how imported and exported functions are called, how data is exchanged, and how errors are handled.
+When the JavaScript environment is itself embedded in a Web browser, the Web API spec [[WASMWEB]] describes additional behavior relevant to the Web environment.
+
 
 <h2 id="sample">Sample API Usage</h2>
 
@@ -733,8 +755,8 @@ which can be simultaneously referenced by multiple {{Instance}} objects. Each
     The <dfn constructor for="Memory">Memory(|descriptor|)</dfn> constructor, when invoked, performs the following steps:
     1. Let |initial| be |descriptor|["initial"].
     1. If |descriptor|["maximum"] [=map/exists=], let |maximum| be |descriptor|["maximum"]; otherwise, let |maximum| be empty.
-    1. If |maximum| is not empty and |maximum| &lt; |initial|, throw a {{RangeError}} exception.
-    1. Let |memtype| be { min |initial|, max |maximum| }.
+    1. Let |memtype| be the [=memory type=] { <b>[=limits|min=]</b> |initial|, <b>[=limits|max=]</b> |maximum| }.
+    1. If |memtype| is not [=valid memtype|valid=], throw a {{RangeError}} exception.
     1. Let |store| be the [=surrounding agent=]'s [=associated store=].
     1. Let (|store|, |memaddr|) be [=mem_alloc=](|store|, |memtype|). If allocation fails, throw a {{RangeError}} exception.
     1. Set the [=surrounding agent=]'s [=associated store=] to |store|.
@@ -894,15 +916,17 @@ Each {{Table}} object has a \[[Table]] internal slot, which is a [=table address
         1. Throw a {{TypeError}} exception.
     1. Let |initial| be |descriptor|["initial"].
     1. If |descriptor|["maximum"] [=map/exists=], let |maximum| be |descriptor|["maximum"]; otherwise, let |maximum| be empty.
-    1. If |maximum| is not empty and |maximum| &lt; |initial|, throw a {{RangeError}} exception.
+    1. Let |type| be the [=table type=] { <b>[=limits|min=]</b> |initial|, <b>[=limits|max=]</b> |maximum| } |elementType|.
+    1. If |type| is not [=valid tabletype|valid=], throw a {{RangeError}} exception.
+
+        Note: Because tables may have up to 2<sup>32</sup> - 1 elements in validation, the checks for [=limits|min=] ≤ 2<sup>32</sup> - 1 and [=limits|max=] ≤ 2<sup>32</sup> - 1 in [=valid limits|limits validation=] cannot fail.
     1. If |value| is missing,
         1. Let |ref| be [=DefaultValue=](|elementType|).
         1. Assert: |ref| is not [=error=].
     1. Otherwise,
         1. Let |ref| be [=?=] [=ToWebAssemblyValue=](|value|, |elementType|).
-    1. Let |type| be the [=table type=] {[=table type|min=] |initial|, [=table type|max=] |maximum|} |elementType|.
     1. Let |store| be the [=surrounding agent=]'s [=associated store=].
-    1. Let (|store|, |tableaddr|) be [=table_alloc=](|store|, |type|, |ref|). <!-- TODO(littledan): Report allocation failure https://github.com/WebAssembly/spec/issues/584 -->
+    1. Let (|store|, |tableaddr|) be [=table_alloc=](|store|, |type|, |ref|). If allocation fails, throw a {{RangeError}} exception.
     1. Set the [=surrounding agent=]'s [=associated store=] to |store|.
     1. [=initialize a table object|Initialize=] **this** from |tableaddr|.
 </div>
@@ -1736,3 +1760,22 @@ In practice, an implementation may run out of resources for valid modules below
 <p><em>This section is non-normative.</em></p>
 
 This document defines a host environment for WebAssembly. It enables a WebAssembly instance to [=import=] JavaScript objects and functions from an [=read the imports|import object=], but otherwise provides no access to the embedding environment. Thus a WebAssembly instance is bound to the same constraints as JavaScript.
+
+<h2 id="change-history">Change History</h2>
+
+<p><em>This section is non-normative.</em></p>
+
+<p>Since the original release 1.0 of the WebAssembly specification, a number of proposals for extensions have been integrated.
+The following sections provide an overview of what has changed.</p>
+
+<h3 id="release-20">Release 2.0</h3>
+
+<h4 id="changes-multivalue" class="no-toc heading settled">Multiple Values</h4>
+Multiple values can be returned from WebAssembly functions into JavaScript as an [=Array=] object.
+
+<h4 id="changes-bigint" class="no-toc heading settled">BigInt Integration</h4>
+WebAssembly [=i64=] values can be passed to and from JavaScript (via imported or exported globals, table get or set operations, function return values or arguments) as [=BigInt=] objects.
+
+<h4 id="changes-reftypes" class="no-toc heading settled">Reference types</h4>
+JavaScript values can be passed to and from WebAssembly (via imported or exported globals, table set or get operations, and function arguments or return values) as [=externref=] values.
+Multiple tables can be exported and imported to and from JavaScript.