[feat] make ($) representation polymorphic

- this change was approved by the CLC in [1] following a CLC proposal [2]
- make ($) representation polymorphic (adjust the type signature)
- change ($) implementation to allow additional polymorphism
- adjust the haddock of ($) to reflect these changes
- add additional documentation to document these changes
- add changelog entry
- adjust tests (move now succeeding tests and adjust stdout of some
  tests)

[1] https://github.com/haskell/core-libraries-committee/issues/132#issuecomment-1487456854
[2] https://github.com/haskell/core-libraries-committee/issues/132

2 files changed, 13 insertions, 4 deletions

diff --git a/libraries/base/GHC/Base.hs b/libraries/base/GHC/Base.hs
index a078676d0f..de99446079 100644
--- a/libraries/base/GHC/Base.hs
+++ b/libraries/base/GHC/Base.hs
@@ -1598,6 +1598,14 @@ const x _               =  x
 flip                    :: (a -> b -> c) -> b -> a -> c
 flip f x y              =  f y x
 
+-- Note: Before base-4.19, ($) was not representation polymorphic
+-- in both type parameters but only in the return type.
+-- The generalization forced a change to the implementation,
+-- changing its laziness, affecting expressions like (($) undefined): before
+-- base-4.19 the expression (($) undefined) `seq` () was equivalent to
+-- (\x -> undefined x) `seq` () and thus would just evaluate to (), but now
+-- it is equivalent to undefined `seq` () which diverges.
+
 -- | Application operator.  This operator is redundant, since ordinary
 -- application @(f x)@ means the same as @(f '$' x)@. However, '$' has
 -- low, right-associative binding precedence, so it sometimes allows
@@ -1608,11 +1616,11 @@ flip f x y              =  f y x
 -- It is also useful in higher-order situations, such as @'map' ('$' 0) xs@,
 -- or @'Data.List.zipWith' ('$') fs xs@.
 --
--- Note that @('$')@ is representation-polymorphic in its result type, so that
--- @foo '$' True@ where @foo :: Bool -> Int#@ is well-typed.
+-- Note that @('$')@ is representation-polymorphic, so that
+-- @foo '$' 4#@ where @foo :: Int# -> Int#@ is well-typed.
 {-# INLINE ($) #-}
-($) :: forall r a (b :: TYPE r). (a -> b) -> a -> b
-f $ x =  f x
+($) :: forall repa repb (a :: TYPE repa) (b :: TYPE repb). (a -> b) -> a -> b
+($) f = f
 
 -- | Strict (call-by-value) application operator. It takes a function and an
 -- argument, evaluates the argument to weak head normal form (WHNF), then calls
diff --git a/libraries/base/changelog.md b/libraries/base/changelog.md
index 76a79abb3f..fcfaed25ec 100644
--- a/libraries/base/changelog.md
+++ b/libraries/base/changelog.md
@@ -21,6 +21,7 @@
       ([CLC proposal #148](https://github.com/haskell/core-libraries-committee/issues/148))
   * Add `COMPLETE` pragmas to the `TypeRep`, `SSymbol`, `SChar`, and `SNat` pattern synonyms.
       ([CLC proposal #149](https://github.com/haskell/core-libraries-committee/issues/149))
+  * Make `($)` representation polymorphic ([CLC proposal #132](https://github.com/haskell/core-libraries-committee/issues/132))
 
 ## 4.18.0.0 *TBA*
   * Shipped with GHC 9.6.1