In particular, we cannot safely rewrite such an invalid call to a runtime

     error; we must emit code that produces a valid Word32#.  (If we're lucky,

     Core Lint may complain that the result of such a rewrite violates

     is always wrong!)  See also Note [Guarding against silly shifts] in

     GHC.Core.Opt.ConstantFold.

   * The "no-float-out" thing is achieved by ensuring that we never let-bind a

     saturated primop application unless it has NoEffect.  The RHS of a

     let-binding (which can float in and out freely) satisfies

     And exprOkForSpeculation is false of a saturated primop application unless it

     has NoEffect.

 A core binding, `CoreBind`, obeys these invariants:

 * For /top level/ or /recursive/ bindings,

 * For /nested/ (not top-level) /non-recursive/ bindings,

 A /top-level/ or /recursive/ binding must

   * have a RHS that is a primitive string literal

 See "Type#type_classification" in GHC.Core.Type

 for the meaning of "lifted" vs. "unlifted".

              S1 = S1

       We allow this top-level unlifted binding to exist.

 A /non-top-level/, /non-recursive/ binding must

   * Be a join point; see Note [Invariants on join points]

 OR

 Historical Note [The let/app invariant]

 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Before 2022 GHC used the "let/app invariant", which applied

 as well as to the RHS of a let.  This made some kind of sense, because 'let' can

 always be encoded as application: let x=rhs in b = (\x.b) rhs

    multiplicity of the corresponding field /scaled by the multiplicity of the

    case binder/. Checked in lintCoreAlt.

 We allow `let` to bind type and coercion variables.

 * A type or coercion binding is always /non-recursive/

 However, join points have simpler invariants in other ways

   5. A join point can have an unboxed type without the RHS being

      e.g.  let j :: Int# = factorial x in ...

   6. The RHS of join point is not required to have a fixed runtime representation,

 mkDoubleLitDouble d = Lit (mkLitDouble (toRational d))

 -- | Bind all supplied binding groups over an expression in a nested let expression.

 mkLets        :: [Bind b] -> Expr b -> Expr b

 -- | Bind all supplied binders over an expression in a nested lambda expression. Prefer to

 -- use 'GHC.Core.Make.mkCoreLams' if possible

   = let out_co = opt_co_refl subst in_co

         (Pair in_l in_r) = coercionKind in_co

         (Pair out_l out_r) = coercionKind out_co

        then out_co

                                        , text "out_l:" <+> ppr out_l

                                        , text "out_r:" <+> ppr out_r

                                        , text "in_co:" <+> ppr in_co

 -- appropriate (see "GHC.Core#let_can_float_invariant")

 mkCoreLet :: HasDebugCallStack => CoreBind -> CoreExpr -> CoreExpr

 mkCoreLet (NonRec bndr rhs) body

     bindNonRec bndr rhs body

 mkCoreLet bind body

   = Let bind body

 all trivial expressions. Consider

    case x |> co of (y::Array# Int) { ... }

 if (x |> co) was not ok-for-speculation.

 But surely (x |> co) is ok-for-speculation, because it's a trivial

     in ...

 This was originally done in the fix to #16449 but this breaks

 reasons discussed under "NoEffect" in Note [Classifying primop effects] (in

 GHC.Builtin.PrimOps) there is no safe way to rewrite the argument of I# such

 that it bottoms.

 Int#/Word#/etc. primops. See builtinBignumRules.

 These rules are built-in because they can't be expressed as regular rules for

 GHC is too conservative with some bignum operations and they don't match rules.

 For example:

 doesn't constant-fold into `integerAdd 2 x` with a regular rule. That's because

 GHC never floats in `integerAdd 1 x` to form `integerAdd 1 (integerAdd 1 x)`

 In the built-in rule for `integerAdd` we can access the unfolding of `r` and we

 can perform the appropriate substitution.

   = isRec is_rec -- Joins are one-shot iff non-recursive

   | definitelyUnliftedType (idType bndr)

           -- see Note [noFloatInto considerations]

   | otherwise

    - noFloatIntoArg: the argument of a function application

 Definitely don't float into RHS if it has unlifted type;

 * Wrinkle 1: do not float in if

      (a) any non-one-shot value lambdas

      let x = a /# 3

 to

      let x = case bx of I# a -> a /# 3

 But (a /# 3) is ok-for-spec due to a special hack that says division operators

 can't fail when the denominator is definitely non-zero.  And yet that same

 expression says False to exprIsCheap.  Simplest way to guarantee

 If an expression is okay for speculation, we could also float it out

 *without* boxing and unboxing, since evaluating it early is okay.

   NonRec x# (y +# 3)    FltOkSpec   -- Unboxed, but ok-for-spec'n

   NonRec x* (f y)       FltCareful  -- Strict binding; might fail or diverge

 -}

 data LetFloats = LetFloats (OrdList OutBind) FloatFlag

   = FltLifted   -- All bindings are lifted and lazy *or*

                 --     consist of a single primitive string literal

                 -- Hence ok to float to top level, or recursive

   | FltOkSpec   -- All bindings are FltLifted *or*

                 --      strict (perhaps because unlifted,

                 -- Hence ok to float out of the RHS

                 -- of a lazy non-recursive let binding

                 -- (but not to top level, or into a rec group)

   | FltCareful  -- At least one binding is strict (or unlifted)

                 --      and not guaranteed cheap

                 -- Do not float these bindings out of a lazy let!

 instance Outputable LetFloats where

   ppr (LetFloats binds ff) = ppr ff $$ ppr (fromOL binds)

      -- Note: Always safe to put the joins on the inside

      -- since the values can't refer to them

   where

 wrapJoinFloatsX :: SimplFloats -> OutExpr -> (SimplFloats, OutExpr)

 -- Wrap the sfJoinFloats of the env around the expression,

               -> (InExpr, SimplEnv)     -- The RHS and its static environment

               -> SimplM (SimplFloats, SimplEnv)

 -- Precondition: Ids only, no TyVars; not a JoinId

 simplLazyBind top_lvl is_rec (bndr,unf_se) (bndr1,env) (rhs,rhs_se)

   = assert (isId bndr )

     assertPpr (not (isJoinId bndr)) (ppr bndr) $

 -- The binder comes from a case expression (case binder or alternative)

 -- and so does not have rules, unfolding, inline pragmas etc.

 --

 simplAuxBind _str env bndr new_rhs

   | assertPpr (isId bndr && not (isJoinId bndr)) (ppr bndr) $

 --      * or by adding to the floats in the envt

 --

 -- Binder /can/ be a JoinId

 completeBind bind_cxt (old_bndr, unf_se) (new_bndr, new_rhs, env)

   | isCoVar old_bndr

   = case new_rhs of

        ; simplExprF (extendTvSubst env bndr ty') body cont }

   | Just env' <- preInlineUnconditionally env NotTopLevel bndr rhs env

     -- inline freely, or to drop the binding if it is dead.

   = do { simplTrace "SimplBindr:inline-uncond2" (ppr bndr <+> ppr rhs) $

          tick (PreInlineUnconditionally bndr)

 completeBindX :: SimplEnv

               -> FromWhat

               -> InId -> OutExpr   -- Non-recursively bind this Id to this (simplified) expression

               -> InExpr            -- In this body

               -> SimplCont         -- Consumed by this continuation

               -> SimplM (SimplFloats, OutExpr)

 completeBindX env from_what bndr rhs body cont

   | FromBeta arg_levity <- from_what

   = do { (env1, bndr1)   <- simplNonRecBndr env bndr  -- Lambda binders don't have rules

        ; (floats, expr') <- simplNonRecBody env1 from_what body cont

        -- Do not float floats past the Case binder below

 -- It deals with strict bindings, via the StrictBind continuation,

 -- which may abort the whole process.

 --

 -- Otherwise it may or may not satisfy it.

 simplNonRecE env from_what bndr (rhs, rhs_se) body cont

   where

     is_strict_bind = case from_what of

        FromBeta Unlifted -> True

        -- If not, the invariant holds already, and it's optional.

        -- (FromBeta Lifted) or FromLet: look at the demand info

 We treat the unlifted and lifted cases separately:

 * Unlifted case: 'e' satisfies exprOkForSpeculation

   This turns     case a +# b of r -> ...r...

   into           let r = a +# b in ...r...

   and thence     .....(a +# b)....

       assert (null bs) $

       do { (floats1, env') <- simplAuxBind "rebuildCase" env case_bndr case_bndr_rhs

              -- scrut is a constructor application,

          ; (floats2, expr') <- simplExprF env' rhs cont

          ; case wfloats of

              [] -> return (floats1 `addFloats` floats2, expr')

 even though it'll be over-ridden in every case alternative with a more

 informative unfolding.  Why?  Because suppose a later, less clever, pass

 simply replaces all occurrences of the case binder with the binder itself;

     case e of b { DEFAULT -> let v = reallyUnsafePtrEquality# b y in ....

                 ; K       -> blah }

 This showed up in #13027.

              -- occur in the RHS; and simplAuxBind may therefore discard it.

              -- Nevertheless we must keep it if the case-binder is alive,

              -- because it may be used in the con_app.  See Note [knownCon occ info]

            ; (floats1, env2) <- simplAuxBind "knownCon" env' b' arg

            ; (floats2, env3) <- bind_args env2 bs' args

            ; return (floats1 `addFloats` floats2, env3) }

     :: SimplEnv -> TopLevelFlag -> InId

     -> InExpr -> StaticEnv  -- These two go together

     -> Maybe SimplEnv       -- Returned env has extended substitution

 -- Reason: we don't want to inline single uses, or discard dead bindings,

 --         for unlifted, side-effect-ful bindings

 preInlineUnconditionally env top_lvl bndr rhs rhs_env

     -> InId -> OutId    -- The binder (*not* a CoVar), including its unfolding

     -> OutExpr

     -> Bool

 -- Reason: we don't want to inline single uses, or discard dead bindings,

 --         for unlifted, side-effect-ful bindings

 postInlineUnconditionally env bind_cxt old_bndr bndr rhs

 Left to itself, the specialiser would float the bindings for `x` and `n` to top

 level, so we can specialise `wombat`.  But we can't have a top-level ByteArray#

 This is pretty exotic, so we take a simple way out: in specBind (the NonRec

 case) do not float the binding itself unless it satisfies exprIsTopLevelBindable.

 This is conservative: maybe the RHS of `x` has a free var that would stop it

 floating to top level anyway; but that is hard to spot (since we don't know what

 the non-top-level in-scope binders are) and rare (since the binding must satisfy

 Note [Specialising Calls]

         -- See Note [Dark corner with representation polymorphism]

         needsCaseBinding (idType b') (snd a)

         -- This arg must not be inlined (side-effects) and cannot be let-bound,

       , let a' = simple_opt_clo (soeInScope env) a

       = mkDefaultCase a' b' $ do_beta env' body as

                                                ; False -> e2 }

                        in ...) ...

   Previously we said yes, on the grounds that y is evaluated.  But the

   binder-swap done by GHC.Core.Opt.SetLevels would transform the inner

   alternative to

      DEFAULT -> ... (let v::Int# = case x of { ... }

                      in ...) ....

   in GHC.Core.Opt.SetLevels.  To avoid this awkwardness it seems simpler

   to stick to unlifted scrutinees where the issue does not

   arise.

 And now the expression does not obey the let-can-float invariant!  Yikes!

 Moreover we really might float (dataToTagLarge# x) outside the case,

 The solution is simple: exprOkForSpeculation does not try to take

 advantage of the evaluated-ness of (lifted) variables.  And it returns

 GHC.Builtin.PrimOps.

 Note that exprIsHNF /can/ and does take advantage of evaluated-ness;

 to worry about.

 ************************************************************************

 see Note [wantFloatLocal].)

 If `v` is bound at the top-level, we might even float `sat` to top-level;

 see Note [Floating out of top level bindings].

 and may exploit strict contexts; see Note [wantFloatLocal].

 There are 3 main categories of floats, encoded in the `FloatingBind` type:

 (FS1) We detect string literals in `cpeBind Rec{}` and float them out anyway;

       otherwise we'd try to bind a string literal in a letrec, violating

       free variables, we float further.

       Arguably, we could just as well relax the letrec invariant for

       string literals, or anthing that is a value (lifted or not).

                x = f y r

                y = [x]

         in e

       So we preempt this case in `wantFloatLocal`, responding `FloatNone` unless

       all floats are `TopLvlFloatable`.

 -}

     , ([1,2],   Opt_DoCleverArgEtaExpansion) -- See Note [Eta expansion of arguments in CorePrep]

     , ([0,1,2], Opt_DoEtaReduction)          -- See Note [Eta-reduction in -O0]

     , ([0,1,2], Opt_ProfManualCcs )

     , ([2], Opt_DictsStrict)

     , ([0],     Opt_IgnoreInterfacePragmas)

 import Unsafe.Coerce

 toLinear

   :: forall a b p q.

      (a %p-> b) %1-> (a %q-> b)

 test('T20023', normal, compile, [''])

 test('T22546', normal, compile, [''])

 test('T23025', normal, compile, ['-dlinear-core-lint'])

 test('LinearRecUpd', normal, compile, [''])

 test('T23814', normal, compile, [''])

 test('LinearLet', normal, compile, [''])