Make all agent allocation imperative

Closes #5210.

Closes #4339 by removing the explicit phrasing of a parallel execution
environment, instead relying on the agent infrastructure.

Closes #4988 by reintroducing a definition for "similar-origin window
agent", separate from its creation algorithm. Like the definition of all
agent types, it is now informal, just stating what globals are contained
in the agent.

Relocates the site-related definitions to the "Origin" section of the
spec, adjacent to the "schemelessly same site" and "same site"
definitions.

Exposes some of the higher-level concepts here to the dev edition.

Author: domenic

source

@@ -2927,6 +2927,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
 
      <li>The <dfn data-x="js-abstract-equality" data-x-href="https://tc39.es/ecma262/#sec-abstract-equality-comparison">Abstract Equality Comparison</dfn> algorithm</li>
      <li>The <dfn data-x="js-strict-equality" data-x-href="https://tc39.es/ecma262/#sec-strict-equality-comparison">Strict Equality Comparison</dfn> algorithm</li>
+     <li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-atomics-object"><code>Atomics</code></dfn> object</li>
      <li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-date-objects"><code>Date</code></dfn> class</li>
      <li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-regexp-regular-expression-objects"><code>RegExp</code></dfn> class</li>
      <li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-sharedarraybuffer-objects"><code>SharedArrayBuffer</code></dfn> class</li>
@@ -79174,6 +79175,31 @@ interface <dfn>BarProp</dfn> {
    </table>
   </div>
 
+  <h4>Sites</h4>
+
+  <p>A <dfn data-export="">scheme-and-registrable-domain</dfn> is a <span>tuple</span> of a <span
+  data-x="concept-url-scheme">scheme</span> and a <span data-x="concept-domain">domain</span>.</p>
+
+  <p>A <dfn data-export="">site</dfn> is an <span data-x="concept-origin-opaque">opaque
+  origin</span>, a <span data-x="concept-origin-tuple">tuple origin</span> whose <span
+  data-x="concept-origin-host">host</span>'s <span>registrable domain</span> is null, or a
+  <span>scheme-and-registrable-domain</span>.</p>
+
+  <p>To <dfn data-export="">obtain a site</dfn>, given an origin <var>origin</var>, run these
+  steps:</p>
+
+  <ol>
+   <li><p>If <var>origin</var> is an <span data-x="concept-origin-opaque">opaque origin</span>, then
+   return <var>origin</var>.</p></li>
+
+   <li><p>If <var>origin</var>'s <span data-x="concept-origin-host">host</span>'s <span>registrable
+   domain</span> is null, then return <var>origin</var>.</p></li>
+
+   <li><p>Return (<var>origin</var>'s <span data-x="concept-origin-scheme">scheme</span>,
+   <var>origin</var>'s <span data-x="concept-origin-host">host</span>'s <span>registrable
+   domain</span>).</p></li>
+  </ol>
+
   <p>Two <span data-x="origin">origins</span>, <var>A</var> and <var>B</var>, are said to be <dfn
   data-export="">schemelessly same site</dfn> if the following algorithm returns true:</p>
 
@@ -88345,79 +88371,73 @@ import "https://example.com/foo/../module2.mjs";</code></pre>
    <li><p>Return « Record { [[Key]]: "url", [[Value]]: <var>urlString</var> } ».</p></li>
   </ol>
 
+  </div>
+
   <h5>Integration with the JavaScript agent formalism</h5>
 
   <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="XXX">JavaScript is expected to define <span data-x="agent">agents</span> in more detail,
-  in particular that <span data-x="JavaScript realm">realms</span> have a pointer to their agent.
-  See <a href="https://github.com/tc39/ecma262/issues/1357">tc39/ecma262 issue #1357</a>. The
-  algorithms which allocate new realms that belong to <span data-x="similar-origin window
-  agent">similar-origin window agents</span> include this pointer. For other realms, the following
-  section describes the relationship.</p>
-
   <div class="note">
    <p>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 needs to run in a single execution thread.</p>
 
-   <p>Two <code>Window</code> objects having the same <span>agent</span> does not indicate they can
-   directly access all objects created in each other's realms. They would have to be <span>same
-   origin-domain</span>; see <span>IsPlatformObjectSameOrigin</span>.</p>
+   <p w-nodev>Two <code>Window</code> objects having the same <span>agent</span> does not indicate
+   they can directly access all objects created in each other's realms. They would have to be
+   <span>same origin-domain</span>; see <span>IsPlatformObjectSameOrigin</span>.</p>
   </div>
 
-  <p>To <dfn data-export="" data-lt="similar-origin window agent" data-x="similar-origin window
-  agent">create a similar-origin window agent</dfn>:</p>
-
-  <ol>
-   <li><p>Let <var>signifier</var> be a new unique internal value.</p></li>
+  <p>The following types of agents exist on the web platform:</p>
 
-   <li><p>Let <var>candidateExecution</var> be a new <span>candidate execution</span>.</p></li>
-
-   <li><p>Return a new <span>agent</span> whose [[CanBlock]] is true, [[Signifier]] is
-   <var>signifier</var>, [[CandidateExecution]] is <var>candidateExecution</var>, and
-   [[IsLockFree1]], [[IsLockFree2]], and [[LittleEndian]] are set at the implementation's
-   discretion.</p></li>
-  </ol>
-
-  <p class="note">All global objects that use this agent all have a similar <span>origin</span> and
-  are allocated via the <span data-x="obtain-similar-origin-window-agent">obtain similar-origin
-  window agent</span> algorithm.</p>
+  <dl>
+   <dt><dfn data-export="">Similar-origin window agent</dfn></dt>
+   <dd>
+    <p>Contains various <code>Window</code> objects which can potentially reach each other, either
+    directly or by using <code data-x="dom-document-domain">document.domain</code>.</p>
 
-  <p>In addition to the above definition for <span>similar-origin window agent</span>, until such a
-  time that this standard has a better handle on lifetimes, it defines the following other types of
-  <span data-x="agent">agents</span> that user agents must allocate at the appropriate time.</p>
+    <p class="note">Two <code>Window</code> objects that are <span>same origin</span> can be in
+    different <span data-x="similar-origin window agent">similar-origin window agents</span>, for
+    instance if they are each in their own <span>browsing context group</span>.</p>
+   </dd>
 
-  <dl>
    <dt><dfn data-export="">Dedicated worker agent</dfn></dt>
-   <dd><p>An <span>agent</span> whose [[CanBlock]] is true and whose set of <span data-x="JavaScript
-   realm">realms</span> consists of a single <code>DedicatedWorkerGlobalScope</code> object's <span
-   data-x="concept-global-object-realm">Realm</span>.</p></dd>
+   <dd><p>Contains a single <code>DedicatedWorkerGlobalScope</code>.</p></dd>
 
    <dt><dfn data-export="">Shared worker agent</dfn></dt>
-   <dd><p>An <span>agent</span> whose [[CanBlock]] is true and whose set of <span data-x="JavaScript
-   realm">realms</span> consists a single <code>SharedWorkerGlobalScope</code> object's <span
-   data-x="concept-global-object-realm">Realm</span>.</p></dd>
+   <dd><p>Contains a single <code>SharedWorkerGlobalScope</code>.</p></dd>
 
    <dt><dfn data-export="">Service worker agent</dfn></dt>
-   <dd><p>An <span>agent</span> whose [[CanBlock]] is false and whose set of <span data-x="JavaScript
-   realm">realms</span> consists of a single <code>ServiceWorkerGlobalScope</code> object's <span
-   data-x="concept-global-object-realm">Realm</span>.</p></dd>
+   <dd><p>Contains a single <code>ServiceWorkerGlobalScope</code>.</p></dd>
 
    <dt><dfn data-export="">Worklet agent</dfn></dt>
    <dd>
-    <p>An <span>agent</span> whose [[CanBlock]] is false and whose set of <span
-    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>Contains a single <code>WorkletGlobalScope</code> object.</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>
 
-  <hr>
+  <p>Only <span data-x="shared worker agent">shared</span> and <span data-x="dedicated worker
+  agent">dedicated worker agents</span> allow the use of JavaScript <code>Atomics</code> APIs to
+  potentially <span data-x="forward progress">block</span>.</p>
+
+  <div w-nodev>
+
+  <p>To <dfn>create an agent</dfn>, given a boolean <var>canBlock</var>:</p>
+
+  <ol>
+   <li><p>Let <var>signifier</var> be a new unique internal value.</p></li>
+
+   <li><p>Let <var>candidateExecution</var> be a new <span>candidate execution</span>.</p></li>
+
+   <li><p>Return a new <span>agent</span> whose [[CanBlock]] is <var>canBlock</var>, [[Signifier]] is
+   <var>signifier</var>, [[CandidateExecution]] is <var>candidateExecution</var>, and
+   [[IsLockFree1]], [[IsLockFree2]], and [[LittleEndian]] are set at the implementation's
+   discretion.</p></li>
+  </ol>
 
   <p>The <dfn data-export="">relevant agent</dfn> for a <span>platform object</span>
   <var>platformObject</var> is the <span>agent</span> whose set of <span data-x="JavaScript
@@ -88427,14 +88447,15 @@ import "https://example.com/foo/../module2.mjs";</code></pre>
   <p class="note">The agent equivalent of the <span>current Realm Record</span> is the
   <span>surrounding agent</span>.</p>
 
+  </div>
+
   <h5>Integration with the JavaScript agent cluster formalism</h5>
 
   <p>JavaScript also defines the concept of an <span>agent cluster</span>, which this standard maps
-  to the web platform using the <span>can share memory with</span> equivalence relation detailed
-  below, as well as explicit allocation of <span data-x="similar-origin window agent">similar-origin
-  window agents</span> to agent clusters. 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>
+  to the web platform by placing agents appropriately when they are created<span w-nodev> using the
+  <span data-x="obtain-similar-origin-window-agent">obtain a similar-origin window agent</span> or
+  <span data-x="obtaining a worker/worklet agent">obtain a worker/worklet agent</span>
+  algorithms</span>.</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
@@ -88448,34 +88469,13 @@ import "https://example.com/foo/../module2.mjs";</code></pre>
   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>
 
+  <div w-nodev>
+
   <hr>
 
   <p>The following defines the allocation of the <span data-x="agent cluster">agent clusters</span>
   of <span data-x="similar-origin window agent">similar-origin window agents</span>.</p>
 
-  <p>A <dfn data-export="">scheme-and-registrable-domain</dfn> is a <span>tuple</span> of a <span
-  data-x="concept-url-scheme">scheme</span> and a <span data-x="concept-domain">domain</span>.</p>
-
-  <p>A <dfn data-export="">site</dfn> is an <span data-x="concept-origin-opaque">opaque
-  origin</span>, a <span data-x="concept-origin-tuple">tuple origin</span> whose <span
-  data-x="concept-origin-host">host</span>'s <span>registrable domain</span> is null, or a
-  <span>scheme-and-registrable-domain</span>.</p>
-
-  <p>To <dfn data-export="">obtain a site</dfn>, given an origin <var>origin</var>, run these
-  steps:</p>
-
-  <ol>
-   <li><p>If <var>origin</var> is an <span data-x="concept-origin-opaque">opaque origin</span>, then
-   return <var>origin</var>.</p></li>
-
-   <li><p>If <var>origin</var>'s <span data-x="concept-origin-host">host</span>'s <span>registrable
-   domain</span> is null, then return <var>origin</var>.</p></li>
-
-   <li><p>Return (<var>origin</var>'s <span data-x="concept-origin-scheme">scheme</span>,
-   <var>origin</var>'s <span data-x="concept-origin-host">host</span>'s <span>registrable
-   domain</span>).</p></li>
-  </ol>
-
   <p>An <dfn>agent cluster key</dfn> is a <span>site</span>.</p>
 
   <p class="XXX"><a href="https://github.com/whatwg/html/pull/4734">whatwg/html #4734</a> is
@@ -88514,8 +88514,8 @@ import "https://example.com/foo/../module2.mjs";</code></pre>
     <ol>
      <li><p>Let <var>agentCluster</var> be a new <span>agent cluster</span>.</p></li>
 
-     <li><p>Add the result of <span data-x="similar-origin window agent">creating a similar-origin
-     window agent</span> to <var>agentCluster</var>.</p></li>
+     <li><p>Add the result of <span data-x="create an agent">creating an agent</span>, given false,
+     to <var>agentCluster</var>.</p></li>
 
      <li><p>Set <var>group</var>'s <span>agent cluster map</span>[<var>key</var>] to
      <var>agentCluster</var>.</p></li>
@@ -88526,47 +88526,67 @@ import "https://example.com/foo/../module2.mjs";</code></pre>
   </ol>
 
   <p class="note">This means that there is only one <span>similar-origin window agent</span> per
-  browsing context agent cluster. (However, other types of agents might be in the same cluster, if
-  they <span>can share memory with</span> the similar-origin window agent.)</p>
+  browsing context agent cluster. (However, <span data-x="dedicated worker agent">dedicated
+  worker</span> and <span data-x="worklet agent">worklet agents</span> might be in the same
+  cluster.)</p>
 
   <hr>
 
-  <p>The allocation of other types of agents to agent clusters is done via the following <dfn>can
-  share memory with</dfn> equivalence relation. Until such a time that this standard has a better
-  handle on the lifetimes of those sorts of agents, user agents must allocate new agent clusters, or
-  reuse ones created via <span data-x="obtain-browsing-agent-cluster">obtain a browsing context
-  agent cluster</span>, in order to ensure that there is an agent cluster for each equivalence class
-  of <span>can share memory with</span>.</p>
+  <p>The following defines the allocation of the <span data-x="agent cluster">agent clusters</span>
+  of all other types of agents.</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
-  memory with</span> any <span>dedicated worker agent</span> whose single <span data-x="JavaScript
-  realm">realm</span>'s <span data-x="concept-realm-global">global object</span>'s <span>owner
-  set</span> contains an item whose <span>relevant agent</span> is <var>agent</var>.</p>
+  <p>To <dfn data-x="obtaining a worker/worklet agent">obtain a worker/worklet agent</dfn>, given an
+  <span>environment settings object</span> <var>owner</var>, a boolean <var>isTopLevel</var>, and a
+  boolean <var>canBlock</var>, run these steps:</p>
 
-  <p class="note">"Item" is used above as an <span>owner set</span> can contain
-  <code>Document</code> objects.</p>
+  <ol>
+   <li>
+    <p>If <var>isTopLevel</var> is true:</p>
 
-  <p>A <span>similar-origin window agent</span> <var>agent</var> <span>can share memory with</span>
-  any <span>worklet agent</span> whose single <span data-x="JavaScript realm">realm</span>'s
-  <span data-x="concept-realm-global">global object</span>'s
-  <span data-x="concept-worklet-owner-document">owner document</span>'s <span>relevant agent</span>
-  is <var>agent</var>.</p>
+    <ol>
+     <li><p>Let <var>agentCluster</var> be a new <span>agent cluster</span>.</p></li>
 
-  <p>In addition, any <span>agent</span> <var>A</var> <span>can share memory with</span>:</p>
+     <li><p>Let <var>agent</var> be the result of <span data-x="create an agent">creating an
+     agent</span> given <var>canBlock</var>.</p></li>
 
-  <ul class="brief">
-   <li><var>A</var>,</li>
+     <li><p>Add <var>agent</var> to <var>agentCluster</var>.</p></li>
 
-   <li>any <span>agent</span> <var>B</var> such that <var>B</var> <span>can share memory with</span>
-   <var>A</var>, and</li>
+     <li><p>Return <var>agent</var>.</p></li>
+    </ol>
+   </li>
 
-   <li>any <span>agent</span> <var>B</var> such that there exists an <span>agent</span>
-   <var>C</var>, where <var>A</var> <span>can share memory with</span> <var>C</var> and <var>C</var>
-   <span>can share memory with</span> <var>B</var>.</li>
-  </ul>
+   <li><p>Let <var>ownerAgent</var> be <var>owner</var>'s <span data-x="environment settings
+   object's Realm">Realm</span>'s agent.</p></li>
 
-  <div class="example">
+   <li><p>Let <var>ownerAgentCluster</var> be the agent cluster which contains
+   <var>ownerAgent</var>.</p></li>
+
+   <li><p>Let <var>agent</var> be the result of <span data-x="create an agent">creating an
+   agent</span> given <var>canBlock</var>.</p></li>
+
+   <li><p>Add <var>agent</var> to <var>ownerAgentCluster</var>.</p></li>
+
+   <li><p>Return <var>agent</var>.</p></li>
+  </ol>
+
+  <p>To <dfn>obtain a dedicated/shared worker agent</dfn>, given an <span>environment settings
+  object</span> <var>owner</var> and a boolean <var>isShared</var>, return the result of
+  <span>obtaining a worker/worklet agent</span> given <var>owner</var>, <var>isShared</var>, and
+  true.</p>
+
+  <p>To <dfn data-export="">obtain a worklet agent</dfn>, given an <span>environment settings
+  object</span> <var>owner</var>, return the result of <span>obtaining a worker/worklet
+  agent</span> given <var>owner</var>, false, and false.</p>
+
+  <p>To <dfn data-export="">obtain a service worker agent</dfn>, given an <span>environment settings
+  object</span> <var>owner</var>, return the result of <span>obtaining a worker/worklet
+  agent</span> given <var>owner</var>, true, and false.</p>
+
+  <hr>
+
+  </div>
+
+  <div class="example" id="can-share-memory-with">
    <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>
 
@@ -88606,8 +88626,6 @@ import "https://example.com/foo/../module2.mjs";</code></pre>
    </ul>
   </div>
 
-  </div>
-
 
   <h5 id="runtime-script-errors">Runtime script errors</h5>
 
@@ -97887,15 +97905,6 @@ interface <dfn>SharedWorkerGlobalScope</dfn> : <span>WorkerGlobalScope</span> {
   <var>options</var>, it must run the following steps.</p>
 
   <ol>
-   <li id="worker-processing-model-top">
-
-    <p>Create a separate parallel execution environment (i.e. a separate thread or process or
-    equivalent construct), and run the rest of these steps in that context.</p>
-
-    <p>For the purposes of timing APIs, this is the <dfn data-export="">official moment of
-    creation</dfn> of the worker.</p>
-   </li>
-
    <li><p>Let <var>is shared</var> be true if <var>worker</var> is a <code>SharedWorker</code>
    object, and false otherwise.</p></li>
 
@@ -97907,11 +97916,24 @@ interface <dfn>SharedWorkerGlobalScope</dfn> : <span>WorkerGlobalScope</span> {
    <li><p>If <var>owner</var> is a <code>WorkerGlobalScope</code> object (i.e., we are creating a
    nested worker), then set <var>parent worker global scope</var> to <var>owner</var>.</p></li>
 
+   <li>
+    <p>Let <var>agent</var> be the result of <span data-x="obtain a dedicated/shared worker
+    agent">obtaining a dedicated/shared worker agent</span> given <var>outside settings</var> and
+    <var>is shared</var>.</p>
+
+    <p id="worker-processing-model-top">For the purposes of timing APIs, this is the <dfn
+    data-export="">official moment of creation</dfn> of the worker.</p>
+   </li>
+
    <li>
     <p>Let <var>realm execution context</var> be the result of <span>creating a new JavaScript
     realm</span> with the following customizations:</p>
 
     <ul>
+     <li><p>For the agent, use <var>agent</var>. <span class="XXX" data-x="">This pointer is not yet
+     defined in the JavaScript specification; see <a
+     href="https://github.com/tc39/ecma262/issues/1357">tc39/ecma262#1357</a>.</span></p></li>
+
      <li><p>For the global object, if <var>is shared</var> is true, create a new
      <code>SharedWorkerGlobalScope</code> object. Otherwise, create a new
      <code>DedicatedWorkerGlobalScope</code> object.</p></li>