Breaking change to await, update to flatten. (#2333)

This PR specifies a breaking change to await, and an update to flatten which includes null safety. In particular, **flatten** is changed such that it is defined for type variables and intersection types. It changes `await` to throw when provided a `Future` value of a type that could provide an unsound value if awaited. This differs from the current specification, which instead treats the future as a value, so `await someFuture` can evaluate to `someFuture`. It also differs from the current implementation, which awaits `someFuture` to its value, whether the result is sound or not.

See also dart-lang/sdk#49396, #2326.

Author: lrhn

specification/dart.sty

@@ -281,7 +281,7 @@
 % name of optional parameters, number of optional parameters.
 \newcommand{\FunctionTypeNamedArguments}[4]{%
   \List{#1}{1}{#2},\ \{\PairList{#1}{#3}{{#2}+1}{{#2}+{#4}}\}}
-  
+
 \newcommand{\FunctionTypeNamedArgumentsStd}{%
   \FunctionTypeNamedArguments{T}{n}{x}{k}}
 
@@ -387,6 +387,12 @@
 \newcommand{\EvaluateElementName}{\metavar{evaluateElement}}
 \newcommand{\EvaluateElement}[1]{\ensuremath{\EvaluateElementName({#1})}}
 
+\newcommand{\DefEquals}[2]{\ensuremath{{#1}\stackrel{\vartriangle}{=}{#2}}}
+\newcommand{\DefEqualsNewline}[2]{
+  \ensuremath{{#1}\stackrel{\vartriangle}{=}}\\
+  \ensuremath{{#2}}%
+}
+
 % ----------------------------------------------------------------------
 % Support for hash valued Location Markers
 

specification/dartLangSpec.tex

@@ -11267,33 +11267,29 @@ \subsection{Function Expressions}
 which is used below and in other sections, as follows:
 
 \begin{itemize}
-\item If $T$ is \code{FutureOr<$S$>} for some $S$ then $\flatten{T} = S$.
+\item{} If $T$ is a type variable $X$ with bound $B$,
+  or $T$ is an intersection type
+  (\ref{intersectionTypes})
+  \code{$X$\,\,\&\,\,$B$},
+  then \DefEquals{\flatten{T}}{\flatten{B}}.
 
-\item Otherwise if
-  \code{$T <:$ Future}
-  then let $S$ be a type such that
-  \code{$T <:$ Future<$S$>}
-  and for all $R$, if
-  \code{$T <:$ Future<$R$>}
-  then $S <: R$.
+\item{} If $T$ is \code{$S$?}\ for some $S$
+  then \DefEquals{\flatten{T}}{\code{\flatten{S}?}}.
 
-  \rationale{%
-    This ensures that
-    \code{Future<$S$>}
-    is the most specific generic instantiation of \code{Future} that is
-    a supertype of $T$.
-    %% TODO[class-interfaces]: When we have finished the specification of class
-    %% interface computations we may have the following property, but it is not
-    %% true at this point. Adjust the following by then!
-    Note that $S$ is well-defined because of
-    the requirements on superinterfaces.%
-  }
+\item{} If $T$ is \code{FutureOr<$S$>} then \DefEquals{\flatten{T}}{S}.
 
-  Then $\flatten{T} = S$.
+\item{} If $T$ implements \code{Future<$S$>}
+  (\ref{interfaceSuperinterfaces})
+  then \DefEquals{\flatten{T}}{S}.
 
-\item In any other circumstance, $\flatten{T} = T$.
+\item{} Otherwise, \DefEquals{\flatten{T}}{T}.
 \end{itemize}
 
+\commentary{%
+This definition guarantees that for any type $T$,
+\code{$T <:$ FutureOr<$\flatten{T}$>}.%
+}
+
 \LMHash{}%
 \Case{Positional, arrow}
 The static type of a function literal of the form
@@ -13755,7 +13751,7 @@ \subsubsection{Ordinary Invocation}
 }
 
 \commentary{%
-An member access on a type literal 
+A member access on a type literal
 (e.g., \code{C.id()}, \code{C.id}, or \code{C?.id()}),
 always treats the declaration denoted by the literal as
 a namespace for accessing static members or constructors.
@@ -15993,11 +15989,18 @@ \subsection{Await Expressions}
 % NOTICE: Removed the requirement that an error thrown by $e$ is caught in a
 % future. There is no reason $var x = e; await x;$ and $await e$ should behave
 % differently, and no implementation actually implemented it.
-If the run-time type of $o$ is a subtype of \code{Future<$T$>},
-then let $f$ be $o$;
-otherwise let $f$ be the result of creating
-a new object using the constructor \code{Future<$T$>.value()}
-with $o$ as its argument.
+Let $R$ be the run-time type of $o$.
+If $R$ implements \code{Future<$S$>} for some $S$
+(\ref{interfaceSuperinterfaces}) then
+it is a dynamic type error if $S$ is not a subtype of $T$.
+Otherwise
+(\commentary{if no run-time error occurred}),
+let $f$ be $o$.
+
+Otherwise
+(\commentary{when $R$ does not implement \code{Future}}),
+let $f$ be an object whose run-time type implements \code{Future<$T$>},
+which is completed with the value $o$.
 
 \LMHash{}%
 Next, the stream associated with the innermost enclosing asynchronous for loop