simplify: remove cyclic binding handling

guybedford · guybedford · commit fd6814043b65 · 2025-03-16T13:48:38.000-07:00
diff --git a/document/js-api/index.bs b/document/js-api/index.bs
@@ -156,6 +156,7 @@ urlPrefix: https://webassembly.github.io/spec/core/; spec: WebAssembly; type: df
     text: memory address; url: exec/runtime.html#syntax-memaddr
     text: global address; url: exec/runtime.html#syntax-globaladdr
     text: extern address; url: exec/runtime.html#syntax-externaddr
+    text: extern subtype; url: valid/types.html#match-externtype
     text: page size; url: exec/runtime.html#page-size
     url: syntax/types.html#syntax-numtype
         text: i32
@@ -1163,7 +1164,7 @@ Note: Exported Functions do not have a \[[Construct]] method and thus it is not
         1. Let |values| be [=?=] [$IteratorToList$]([=?=] [$GetIteratorFromMethod$](|ret|, |method|)).
         1. Let |wasmValues| be a new, empty [=list=].
         1. If |values|'s [=list/size=] is not |resultsSize|, throw a {{TypeError}} exception.
-        1. [=list/iterate|For each=] |value| and |resultType| in |values| and |results|, paired linearly,
+        1. For each |value| and |resultType| in |values| and |results|, paired linearly,
             1. [=list/Append=] [=ToWebAssemblyValue=](|value|, |resultType|) to |wasmValues|.
         1. Return |wasmValues|.
 </div>
@@ -1388,9 +1389,11 @@ To <dfn export>parse a WebAssembly module</dfn> given a <a>byte sequence</a> |by
 1. If |module| is [=error=], throw a {{CompileError}} exception.
 1. [=Construct a WebAssembly module object=] from |module| and |bytes|, and let |module| be the result.
 1. Let |requestedModules| be a set.
-1. [=list/iterate|For each=] (|moduleName|, <var ignore>name</var>, <var ignore>type</var>) in [=module_imports=](|module|.\[[Module]]),
+1. For each (|moduleName|, <var ignore>name</var>, <var ignore>type</var>) in [=module_imports=](|module|.\[[Module]]),
     1. [=set/Append=] |moduleName| to |requestedModules|.
 1. Let |moduleRecord| be {
+      <!-- WebAssembly Module Records -->
+      \[[Instance]]: ~empty~,
       <!-- Abstract Module Records -->
       \[[Realm]]: |realm|,
       \[[Environment]]: ~empty~,
@@ -1422,7 +1425,7 @@ The <dfn>export name list</dfn> of a WebAssembly Module Record |record| is defin
 
 1. Let |module| be |record|'s \[[ModuleSource]] internal slot.
 1. Let |exports| be an empty [=list=].
-1. [=list/iterate|For each=] (|name|, <var ignore>type</var>) in [=module_exports=](|module|.\[[Module]])
+1. For each (|name|, <var ignore>type</var>) in [=module_exports=](|module|.\[[Module]])
     1. [=list/Append=] |name| to the end of |exports|.
 1. Return |exports|.
 
@@ -1483,9 +1486,9 @@ WebAssembly Module Records have the following methods:
         1. Let |resolutionName| be |resolution|.\[[BindingName]].
         1. Let |externval| be [=instance_export=](|resolutionInstance|, |resolutionName|).
         1. Assert: |externval| is not [=error=].
-        1. Assert: [=module_direct_exports=](|resolutionModule|) contains an element (|resolutionName|, <var ignore>type</var>).
-        1. Let |externtype| be the value of |type| for the element (|resolutionName|, |type|) in [=module_direct_exports=](|resolutionModule|).
-        1. If [=module_extern_subtype=](|externtype|, |importtype|) is false, throw a {{LinkError}} exception.
+        1. Assert: [=module_exports=](|resolutionModule|) contains an element (|resolutionName|, <var ignore>type</var>).
+        1. Let |externtype| be the value of |type| for the element (|resolutionName|, |type|) in [=module_exports=](|resolutionModule|).
+        1. If |importtype| is not an [=extern subtype=] of |externtype|, throw a {{LinkError}} exception.
         1. [=list/Append=] |externval| to |imports|.
     1. Otherwise,
         1. Let |env| be |resolution|.\[[Module]].\[[Environment]].
@@ -1500,13 +1503,15 @@ WebAssembly Module Records have the following methods:
             1. Let |externfunc| be the [=external value=] [=external value|func=] |funcaddr|.
             1. [=list/Append=] |externfunc| to |imports|.
         1. If |importtype| is of the form [=global=] |mut| |valtype|,
+            1. Let |store| be the [=surrounding agent=]'s [=associated store=].
             1. If |v| [=implements=] {{Global}},
                 1. Let |globaladdr| be |v|.\[[Global]].
+                1. Let |targetmut| <var ignore>valuetype</var> be [=global_type=](|store|, |globaladdr|).
+                    1. If |mut| is [=const=] and |targetmut| is [=var=], throw a {{TypeError}}.
             1. Otherwise,
-                1. If |valtype| is [=v128=],
-                    1. Throw a {{LinkError}} exception.
+                1. If |valtype| is [=v128=], throw a {{LinkError}} exception.
+                1. If |mut| is [=var=], throw a {{TypeError}}.
                 1. Let |value| be [=?=] [=ToWebAssemblyValue=](|v|, |valtype|).
-                1. Let |store| be the [=surrounding agent=]'s [=associated store=].
                 1. Let (|store|, |globaladdr|) be [=global_alloc=](|store|, |mut| |valtype|, |value|).
                 1. Set the [=surrounding agent=]'s [=associated store=] to |store|.
             1. Let |externglobal| be [=external value|global=] |globaladdr|.
@@ -1522,53 +1527,34 @@ WebAssembly Module Records have the following methods:
             1. [=list/Append=] |externtable| to |imports|.
 1. [=Instantiate the core of a WebAssembly module=] |module| with |imports|, and let |instance| be the result.
 1. Set |record|.\[[Instance]] to |instance|.
-1. [=list/iterate|For each=] (|name|, |externtype|) of [=module_direct_exports=](|module|),
-    1. Let |externval| be [=instance_export=](|instance|, |name|).
-    1. Assert: |externval| is not [=error=].
-    1. If |externtype| is of the form [=func=] <var ignore>functype</var>,
-        1. Assert: |externval| is of the form [=external value|func=] |funcaddr|.
-        1. Let [=external value|func=] |funcaddr| be |externval|.
-        1. Let |func| be the result of creating [=a new Exported Function=] from |funcaddr|.
-        1. Perform [=!=] |record|.\[[Environment]].InitializeBinding(|name|, |func|).
+1. [=list/iterate|For each=] (|name|, |externtype|) of [=module_exports=](|module|),
     1. If |externtype| is of the form [=global=] |mut| |globaltype|,
         1. Assert: |externval| is of the form [=external value|global=] |globaladdr|.
         1. Let [=external value|global=] |globaladdr| be |externval|.
         1. Let |global_value| be [=global_read=](|store|, |globaladdr|).
         1. If |globaltype| is not [=v128=],
-            1. Note: When integrating with shared globals, they will be excluded here similarly to v128 above.
+            1. Note: The condition above leaves unsupported JS values as uninitialized in TDZ and therefore as a reference error on
+                access. When integrating with shared globals, they may be excluded here similarly to v128 above. 
             1. Perform [=!=] |record|.\[[Environment]].InitializeBinding(|name|, [=ToJSValue=](|global_value|)).
-            1. Associate all future mutations to the mutable value at |globaladdr| with the ECMA-262 binding record for |name| in
+            1. If |mut| is [=var=], then associate all future mutations of |globaladdr| with the ECMA-262 binding record for |name| in
                 |record|.\[[Environment]], such that |record|.\[[Environment]].GetBindingValue(|resolution|.\[[BindingName]], true)
                 always returns [=ToJSValue=]([=global_read=](|store|, |globaladdr|)) for the current [=surrounding agent=]'s
                 [=associated store=] |store|.
-    1. If |externtype| is of the form [=mem=] <var ignore>memtype</var>,
-        1. Assert: |externval| is of the form [=external value|mem=] |memaddr|.
-        1. Let [=external value|mem=] |memaddr| be |externval|.
-        1. Let |memory| be [=create a memory object|a new Memory object=] created from |memaddr|.
-        1. Perform [=!=] |record|.\[[Environment]].InitializeBinding(|name|, |memory|).
-    1. If |externtype| is of the form [=table=] <var ignore>tabletype</var>,
-        1. Assert: |externval| is of the form [=external value|table=] |tableaddr|.
-        1. Let [=external value|table=] |tableaddr| be |externval|.
-        1. Let |table| be [=create a Table object|a new Table object=] created from |tableaddr|.
-        1. Perform [=!=] |record|.\[[Environment]].InitializeBinding(|name|, |table|).
-
-Note: The export bindings for a WebAssembly Module Record are designed to mirror the live bindings of all directly exported values. Values not
-supported in JS are left uninitialized and in TDZ, while still being accesible to Wasm importers. Indirect exports (re-exports) referencing
-JavaScript values will capture the [=ToWebAssemblyValue=] interpretation at the time of execution, while indirect exports resolving to other Wasm
-modules will support Wasm live bindings. For exported mutable globals that are supported in JavaScript, the live bindings on the environment record
-will always reflect the current mutable global export value as interpreted through the infallible [=ToJSValue=] interpretation.
+    1. Otherwise,
+        1. Perform ! |record|.\[[Environment]].InitializeBinding(|name|, ! Get(|instance|.\[[Exports]], |name|)).
 
 </div>
 
 <h3 id="hostgetmodulesourcemodulerecord">HostGetModuleSourceModuleRecord ( |specifier| )</h3>
 1. If |specifier| is a WebAssembly {{Module}} object with a \[[Module]] internal slot,
-    1. Let |module| be |specifier|.\[[Module]].
-    1. If |module|.\[[ModuleRecord]] is null,
+    1. If |specifier|.\[[Module]].\[[ModuleRecord]] is null,
         1. Let |realm| be the current agent's realm record.
         1. Let |requestedModules| be a set.
-        1. [=list/iterate|For each=] (|moduleName|, <var ignore>name</var>, <var ignore>type</var>) in [=module_imports=](|module|),
+        1. For each (|moduleName|, <var ignore>name</var>, <var ignore>type</var>) in [=module_imports=](|specifier|.\[[Module]]),
             1. [=set/Append=] |moduleName| to |requestedModules|.
         1. Let |moduleRecord| be {
+              <!-- WebAssembly Module Records -->
+              \[[Instance]]: ~empty~,
               <!-- Abstract Module Records -->
               \[[Realm]]: |realm|,
               \[[Environment]]: ~empty~,
@@ -1591,7 +1577,7 @@ will always reflect the current mutable global export value as interpreted throu
             }.
         1. Set |module|.\[[ModuleRecord]] to |moduleRecord|.
         1. Return |moduleRecord|.
-    1. Return |module|.\[[ModuleRecord]].
+    1. Return |specifier|.\[[Module]].\[[ModuleRecord]].
 1. Return ~not-a-source~.
 
 Note: See corresponding modifications to HTML in <a href="https://github.com/whatwg/html/pull/10380">PR #10380</a>.
diff --git a/proposals/esm-integration/EXAMPLES.md b/proposals/esm-integration/EXAMPLES.md
@@ -123,13 +123,17 @@ for (let index = 0; index < length; index++)
 | table       | `WebAssembly.Table` object  |
 | function    | WebAssembly exported function |
 
+Wasm bindings cannot be reassigned as it can in JS, so the exported value will not change in their object identity. But the value that it points to (e.g. `.value` in the case of `WebAssembly.Global`) can change.
+
 1. JS module is parsed
 1. wasm module is parsed
 1. wasm module has a lexical environment created for its exports. All exports are initially in TDZ.
 1. JS module is instantiated. Imports are bound to the same memory locations.
 1. wasm module is instantiated evaluated. Functions are initialized. Memories and tables are initialized and filled with data/elem sections. Globals are initialized and initializer expressions are evaluated. The start function runs.
 1. JS module is evaluated. All values are available.
 
+The value of the export for `WebAssembly.Global` is provided directly on the JS namespace object, with mutable globals reflected as live bindings to JS.
+
 #### Example
 
 ```js
@@ -177,7 +181,7 @@ Wasm exports can be imported as accurate, immutable bindings to other wasm modul
 
 ### wasm imports <- JS re-exports <- wasm exports
 
-Any wasm exports that are re-exported via a JS module will be available to the other wasm module as accurate bindings. If the binding is a mutable global, then that binding will be a live export binding in JS reflecting changes to the Wasm global value. When imported from JS, the first and second Wasm modules will yield the same Wasm identities for the multiply exported Wasm objects.
+Any wasm exports that are re-exported via a JS module will be available to the other wasm module as accurate, immutable bindings. The wasm export gets wrapped into a JS object (e.g. `WebAssembly.Global`) and then unwrapped to the wasm import in the importing wasm module. When imported from JS, the first and second Wasm modules will yield the same object identities for the multiply exported Wasm objects.
 
 #### Example
 
@@ -213,7 +217,7 @@ export {memoryExport} from "./b.wasm";
 
 1. JS module is parsed
 1. wasm module is parsed
-1. wasm module has a lexical environment created for its exports. All direct exports are initially in TDZ, indirect exports are available as they resolve.
+1. wasm module has a lexical environment created for its exports. All exports are initially in TDZ.
 1. JS module is instantiated. All imports (including functions) from the wasm module are memory locations holding undefined.
 1. wasm module is instantiated and evaluated. Snapshots of imports are taken. Export bindings are initialized.
 1. JS module is evaluated. 
@@ -251,8 +255,8 @@ export function functionExport() {
 1. wasm module is parsed
 1. JS module is parsed
 1. JS module is instantiated. 
-1. wasm module has a lexical environment created for its exports. All direct exports are initially in TDZ, indirect exports are available as they resolve.
-1. JS module is evaluated. wasm exports in TDZ lead to a ReferenceError if used.
+1. wasm module has a lexical environment created for its exports. All exports are initially in TDZ.
+1. JS module is evaluated. wasm exports lead to a ReferenceError if used.
 1. wasm module is instantiated and evaluated; wasm-exported bindings are updated to their appropriate JS API-exposed values. 
 
 #### Examples
diff --git a/proposals/esm-integration/README.md b/proposals/esm-integration/README.md
@@ -94,22 +94,23 @@ In the proposed HTML integration of WebAssembly modules, the [module name](https
 
 ### "Snapshotting" imports
 
-When imports are provided to WebAssembly modules in the host instance linking model from JavaScript, they are provided directly upfront.
+When imports are provided to WebAssembly modules in the host instance linking model, they are provided directly upfront.
 
 - This handling of imports could be called a "snapshotting" process: Later updates to the imported values won't be reflected within the WebAssembly module.
-- Circular WebAssembly module bindings are not supported for direct exports: One of them will run first, and that one will find that the exports of the other aren't yet initialized, leading to a ReferenceError. Indirect exports (reexports) can be supported early in Wasm cycles, where a WebAssembly module exports the same binding it imports.
+- Circular WebAssembly modules are not supported: One of them will run first, and that one will find that the exports of the other aren't yet initialized, leading to a ReferenceError.
 
 See the FAQ for more explanation of the rationale for this design decision, and what features it enables which would be difficult or impossible otherwise.
 
-### Live binding exports
+### Progressive Implementation Support
 
-WebAssembly modules support live exports bindings for mutable globals by reflecting the infallible ToJsValue() representation of their mutable global exports on their JavaScript environment bindings record.
+It is possible to implement the Wasm-ESM integration in two stages:
 
-For bindings that are exported from bindings that were initially imported i.e. indirect exports or reexports:
+1. In the first stage only source phase imports of Wasm are supported (`import source fibModule from "./fib.wasm"`).
+2. In the second stage, evaluation phase imports would be supported too (`import { fib } from "./fib.wasm"`).
 
-1. WebAssembly modules that have indirect exports to JavaScript modules, these values are snapshotted at the time of execution of the WebAssembly module and reflected as captured bindings and not live bindings on the exports, even if the underlying JavaScript module might have modifications to the binding later on.
+If initially implementing just source phase imports, the `GetExportedNames`, `ResolveExport`, `InitializeEnvironment`, and `ExecuteModule` abstract operations can be implemented as abstract operations unconditionally throwing a `SyntaxError` exception. In this case, module fetch and CSP integration is still required to be implemented as specified in this proposal.
 
-2. WebAssembly modules that have indirect exports to WebAssembly modules, where those modules directly export mutable globals, support the live mutable global reference without capturing the import.
+Implementers are encouraged to ship both stages at once, but it is deemed OK for implementers to initially ship the first stage and then quickly follow up with the second stage, if this aids "time to ship" in implementations.
 
 ## FAQ
 
@@ -119,7 +120,7 @@ Originally the ESM integration only provided the direct host instance linking mo
 
 Supporting the [source phase](https://github.com/tc39/proposal-source-phase-imports) ESM integration is therefore a more general form of the ESM integration that shares the host resolver, while retaining linking flexibility for Js host embedding of Wasm.
 
-While the source phase does not replace the instance linking model, is does offer a more general and flexible ESM integration as an addition.
+While the source phase does not replace the instance linking model, is does offer a more general and flexible ESM integration.
 
 ### How does this relate to the Component Model?
 
@@ -149,7 +150,7 @@ The conversion is based on the type that the import and export was declared as,
 
 ### When one WebAssembly module imports another one, will there be overhead due to converting back and forth to JS values?
 
-Bindings between WebAssembly modules, even those that are indirect through indirect exports (reexports) are directly linked, without needing to go through JS wrapping and unwrapping.
+Note that exports of ES Module Records always have values that can be directly treated as JavaScript values. Although we're talking about conversions to and from JavaScript for these exports, it's expected that, in native implementations, the conversion to and from Javascript would "cancel out" and not lead to the use of wrappers in practice.
 
 ### Why are WebAssembly modules instantiated during the "Evaluation" phase?
 
@@ -171,11 +172,9 @@ Instead of including this check in the default semantics of functions, a trampol
 
 ### What does snapshotting imports mean for importing globals?
 
-Imports are only snapshotted when they resolve to a JavaScript module. For imports that resolve to WebAssembly modules, these are always directly bound.
-
-When a WebAssembly module imports a Global, that resolves to a module after resolving the binding through any indirect exports (reexports):
-- If the resolved module is a JavaScript module, then the exporting module may either export a direct value or a `WebAssembly.Global` of the same type.
-- If the resolved module is a WebAssembly module, then the exporting module must export a global that is an extern subtype of the importing global.
+When a WebAssembly module imports a Global, there are two possible modes of operation:
+- If the Global type is immutable (as declared in the importing module), then the exporting module may either export a numeric value or an immutable Global.
+- If the Global type is mutable, then the exporting module must export a mutable Global. The snapshot here is "shallow" in the sense that modifications *within* this particular mutable Global object *will* be visible in the importing module (but, if the exporting module overwrites the entire binding with some unrelated value, this will not be noticed by the importing module).
 
 ### Can Web APIs be imported via modules?
 
