comment only

compiler/coreSyn/CoreSyn.hs

@@ -183,9 +183,17 @@ These data types are the heart of the compiler
 --
 --    The right hand sides of all top-level and recursive @let@s
 --    /must/ be of lifted type (see "Type#type_classification" for
---    the meaning of /lifted/ vs. /unlifted/).
+--    the meaning of /lifted/ vs. /unlifted/), with two exceptions:
 --
---    See Note [CoreSyn let/app invariant]
+--    1. The right hand side of a top-level @let@ may be a primitive string literal
+--       (of type @Addr#@). This exception allows primitive string literals to
+--       be floated out to the top level. Without this, these literals may
+--       prevent floating of bindings that use them. See #8472.
+--
+--    2. The right hand side of a top-level @let@ may be a variable of type
+--       @Addr#@. Such a binding is usually a result of a CSE pass.
+--
+--    Also see Note [CoreSyn let/app invariant]
 --
 --    #type_let#
 --    We allow a /non-recursive/ let to bind a type variable, thus:

docs/core-spec/core-spec.mng

@@ -100,7 +100,9 @@ The datatype that represents expressions:
 There are a few key invariants about expressions:
 \begin{itemize}
 \item The right-hand sides of all top-level and recursive $[[let]]$s
-must be of lifted type.
+must be of lifted type, with one exception: the right-hand side of a top-level
+$[[let]]$ may be of type \texttt{Addr#} if it's a primitive string literal or
+a single variable. See \verb|#top_level_invariant#| in \ghcfile{coreSyn/CoreSyn.hs}.
 \item The right-hand side of a non-recursive $[[let]]$ and the argument
 of an application may be of unlifted type, but only if the expression
 is ok-for-speculation. See \verb|#let_app_invariant#| in \ghcfile{coreSyn/CoreSyn.lhs}.