Clarify and explain agents and agent clusters

* Explain the agent ↔ thread and agent cluster ↔ process boundary
  connection. See the most recent example of the editors explaining this
  to folks in #3766.
* Fix misleading note about how agents map to worklets.
* Add an example showing that two same-origin, but unrelated, Windows
  are in different agent clusters.
* Tidy up and rearrange some of the introductory material to each
  section.

Author: domenic

source

@@ -88378,19 +88378,26 @@ import "https://example.com/foo/../module2.mjs";</code></pre>
 
   <h5>Integration with the JavaScript agent formalism</h5>
 
-  <p>JavaScript defines the concept of an <span>agent</span>. Until such a time that this standard
-  has a better handle on lifetimes, we define five types of <span data-x="agent">agents</span> that
-  user agents must allocate at the appropriate time.</p>
-
-  <p class="note">In the future, when this specification has a better handle on lifetimes, we hope
-  to define exactly when <span data-x="agent">agents</span> and <span data-x="agent cluster">agent
-  clusters</span> are created.</p>
+  <p>JavaScript defines the concept of an <span>agent</span>. This section gives the mapping of that
+  language-level concept on to the web platform.</p>
 
   <p class="&#x0058;&#x0058;&#x0058;">JavaScript is expected to define <span
   data-x="agent">agents</span> in more detail; in particular that they hold a set of <span
   data-x="concept-global-object-realm">realms</span>: <a
   href="https://github.com/tc39/ecma262/issues/882">tc39/ecma262 issue #882</a>.</p>
 
+  <p class="note">Conceptually, the <span>agent</span> concept is an architecture-independent,
+  idealized "thread" in which JavaScript code runs. Such code can involve multiple globals/<span
+  data-x="concept-global-object-realm">realms</span> that can synchronously access each other, and
+  thus need to run in a single execution thread.</p>
+
+  <p>Until such a time that this standard has a better handle on lifetimes, it defines five types of
+  <span data-x="agent">agents</span> that user agents must allocate at the appropriate time.</p>
+
+  <p class="note">In the future, this standard hopes to define exactly when <span
+  data-x="agent">agents</span> and <span data-x="agent cluster">agent clusters</span> are
+  created.</p>
+
   <dl>
    <dt><dfn data-export="">Similar-origin window agent</dfn></dt>
    <dd>
@@ -88427,16 +88434,30 @@ import "https://example.com/foo/../module2.mjs";</code></pre>
     data-x="JavaScript realm">realms</span> consists of a single <code>WorkletGlobalScope</code>
     object's <span data-x="concept-global-object-realm">Realm</span>.</p>
 
-    <p class="note">While conceptually it might be cleaner for worklets that end up with multiple
-    realms to put all those in the same agent, it is not observable in practice.</p>
+    <p class="note">Although a given worklet can have multiple realms, each such realm needs its own
+    agent, as each realm can be executing code independently and at the same time as the others.</p>
    </dd>
   </dl>
 
   <h5>Integration with the JavaScript agent cluster formalism</h5>
 
-  <p><dfn>Can share memory with</dfn> defines an equivalence relation. An <span>agent cluster</span>
-  consists of all <span data-x="agent">agents</span> in the same equivalence class with respect to
-  the <span>can share memory with</span> equivalence relation.</p>
+  <p>JavaScript also defines the concept of an <span>agent cluster</span>, which this standard maps
+  to the web platform using the <dfn>can share memory with</dfn> equivalence relation detailed
+  below. On the web platform, an <span>agent cluster</span> consists of all <span
+  data-x="agent">agents</span> in the same equivalence class with respect to the <span>can share
+  memory with</span> equivalence relation.</p>
+
+  <p>The <span>agent cluster</span> concept is crucial for defining the JavaScript memory model, and
+  in particular among which <span data-x="agent">agents</span> the backing data of
+  <code>SharedArrayBuffer</code> objects can be shared.</p>
+
+  <p class="note">Conceptually, the <span>agent cluster</span> concept is an
+  architecture-independent, idealized "process boundary" that groups together multiple "threads"
+  (<span data-x="agent">agents</span>). The <span data-x="agent cluster">agent clusters</span>
+  defined by the specification are generally more restrictive than the actual process boundaries
+  implemented in user agents. By enforcing these idealized divisions at the specification level, we
+  ensure that web developers see interoperable behavior with regard to shared memory, even in the
+  face of varying and changing user agent process models.</p>
 
   <p>A <span>similar-origin window agent</span>, <span>dedicated worker agent</span>, <span>shared
   worker agent</span>, or <span>service worker agent</span>, <var>agent</var>, <span>can share
@@ -88445,8 +88466,8 @@ import "https://example.com/foo/../module2.mjs";</code></pre>
   set</span> contains an item whose <span data-x="concept-relevant-realm">relevant Realm</span>
   belongs to <var>agent</var>.</p>
 
-  <p class="note">We use item above as an <span>owner set</span> can contain <code>Document</code>
-  objects.</p>
+  <p class="note">"Item" is used above as an <span>owner set</span> can contain
+  <code>Document</code> objects.</p>
 
   <p class="&#x0058;&#x0058;&#x0058;">A <span>worklet agent</span> &hellip; currently worklets have
   no clearly defined owner, see: <a
@@ -88466,10 +88487,6 @@ import "https://example.com/foo/../module2.mjs";</code></pre>
    <span>can share memory with</span> <var>B</var>.</li>
   </ul>
 
-  <p>The <span>agent cluster</span> concept is crucial for defining the JavaScript memory model, and
-  in particular among which <span data-x="agent">agents</span> the backing data of
-  <code>SharedArrayBuffer</code> objects can be shared.</p>
-
   <div class="example">
    <p>The following pairs of global objects are each within the same <span>agent cluster</span>, and
    thus can use <code>SharedArrayBuffer</code> instances to share memory with each other:</p>
@@ -88500,6 +88517,11 @@ import "https://example.com/foo/../module2.mjs";</code></pre>
     <li>A <code>Window</code> object <var></var> and the <code>Window</code> object of an
     <code>iframe</code> element that <var>A</var> created that cannot be <span>same
     origin-domain</span> with <var>A</var>.</li>
+
+    <li>Any two <code>Window</code> objects whose <span data-x="browsing context">browsing
+    contexts</span> do not have an <span data-x="opener browsing context">opener</span> or <span
+    data-x="ancestor browsing context">ancestor</span> relationship. This holds even if the two
+    <code>Window</code> objects are <span>same origin</span>.</li>
    </ul>
   </div>