+https://downloads.haskell.org/ghc/latest/docs/users_guide/exts/instances.html#instance-overlap

+      the search fails unless -XIncoherentInstances is enabled. See

+      Note [Instance and Given overlap] in GHC.Tc.Solver.Dict.  This is

+      implemented by the first guard in matchClassInst.

+

+(IL1) Find `all_matches` and `all_unifs` in `lookupInstEnv`:

+      - all_matches: all instances `I` that *match* the target constraint (that

+        is, the target constraint is a substitution instance of `I`). These

+        instance declarations are the /candidates/.

+      - all_unifs: all non-incoherent instances that *unify with but do not match*

+        the target constraint. These are not candidates, but might match later if

+        the target constraint is furhter instantiated. See

+        `data PotentialUnifiers` for more precise details.

+

+(IL2) If there are no candidates, the search fails

+      (lookupInstEnv returns no final_matches). The PotentialUnifiers are returned

+      by lookupInstEnv for use in error message generation (mkDictErr).

+      In addition, provided there is at least one candidate, eliminate any other

+      candidates that are *incoherent*. (In particular, if all remaining candidates

+      are incoherent, all except an arbitrarily chosen one will be eliminated.)

+

+      This is implemented by `pruneOverlappedMatches`, producing final_matches in

+      lookupInstEnv.  See Note [Instance overlap and guards] and

+      Note [Incoherent instances].

+

+(IL4) If exactly one *incoherent* candidate remains, the search succeeds.

+      (By the previous step, there cannot be more than one incoherent candidate

+      remaining.)

+      In this case, lookupInstEnv returns the successful match, and it returns

+      NoUnifiers as the final_unifs, which amounts to skipping the following

+      steps.

+(IL5) If more than one candidate remains, the search fails. (We have already

+      eliminated the incoherent candidates, and we have no way to select

+      between non-incoherent candidates.)

+(IL6) Otherwise there is exactly one candidate remaining. The all_unifs

+      computed at step (IL1) are returned from lookupInstEnv as final_unifs.

+      If there are no potential unifiers, the search succeeds (in matchInstEnv).

+      If there is at least one (non-incoherent) potential unifier, matchInstEnv

+      returns a NotSure result and refrains from committing to the instance.

+

+      Incoherent instances are not returned as part of the potential unifiers. This

+      affects error messages: they will not be listed as "potentially matching instances"

+      in an "Overlapping instances" or "Ambiguous type variable" error.

+      See also Note [Recording coherence information in `PotentialUnifiers`].

+* We label as "non-canonical" any dictionary constructed by a (potentially)

+  incoherent use of an ClsInst.

+  in step (IL4) or (IL6) of the instance lookup: see

+  Note [Recording coherence information in `PotentialUnifiers`] and

+  Note [Canonicity for incoherent matches].

+

+

+Note [Canonicity for incoherent matches]

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+When the selected instance is INCOHERENT at step (IL4) of

+Note [Rules for instance lookup], we ignore all unifiers,

+whether or not they are marked with INCOHERENT pragmas.

+This is implemented by returning NoUnifiers in final_unifs.

+NoUnifiers takes an argument indicating whether the match was canonical

+as described in Note [Coherence and specialisation: overview] and

+Note [Recording coherence information in `PotentialUnifiers`].

+

+To determine whether an incoherent match was canonical, we look *only*

+at the OverlapFlag of the instance being matched. For example:

+

+  class C a

+  instance {-# INCOHERENT #-} C a -- (1)

+  instance C Int   -- (2)

+

+  [W] C tau

+

+Here we match instance (1) and discard instance (2). If (1) is Incoherent

+(under -fspecialise-incoherents), it is important that we treat the match

+as EvCanonical so that we do not block specialisation (see #25883).

+

+What about the following situation:

+

+  instance {-# INCOHERENT #-} C a    -- (1), in a module with -fspecialise-incoherents (Incoherent)

+  instance {-# INCOHERENT #-} C Int  -- (2), in a module with -fno-specialise-incoherents (NonCanonical)

+

+  [W] C tau

+

+Again we match instance (1) and discard instance (2). It is not obvious

+whether Incoherent or NonCanonical should "win" here, but it seems more

+consistent with the previous example to look only at the flag on instance (1).

+

+What about if the only instance that can match is marked as NonCanonical?

+In this case are no unifiers at all, so all_unifs = NoUnifiers EvCanonical.

+It is not obvious what -fno-specialise-incoherents should do here, but

+currently it returns NoUnifiers EvCanonical.

+

+don't care (see step (IL6) in Note [Rules for instance lookup]).

+But if we have potentially unifying coherent instance, we

+

+For example, suppose we have:

+

+  class C x y

+  instance C a Bool                   -- (1)

+  instance {-# INCOHERENT #-} C Int a -- (2)

+

+  [W] C x Bool

+

+Here instance (1) matches the Wanted, and since instance (2) is INCOHERENT

+we want to succeed with the match rather than getting stick at step (IL6).

+But if -fno-specialise-incoherents was enabled for (2), the specialiser is

+not permitted to specialise this dictionary later, so lookupInstEnv reports

+the PotentialUnifiers as NoUnifiers EvNonCanonical.

+

+-- | Are there no *coherent* unifiers?

+-- | Are there any unifiers, ignoring those marked Incoherent (but including any

+-- marked NonCanonical)?

+someUnifiers :: PotentialUnifiers -> Bool

+someUnifiers (NoUnifiers EvCanonical) = False

+someUnifiers _ = True

+

+

+    -- (IL1): Find all instances that match the target constraint

+

+    -- (IL3): Eliminate candidates that are overlapped or incoherent

+                           -- if the match is non-canonical.

+                           -- See Note [Canonicity for incoherent matches]

+                              NoUnifiers $

+                                 if isNonCanonical (fst m) && someUnifiers all_unifs

+                                    then EvNonCanonical

+                                    else EvCanonical

+-- See Note [Instance and Given overlap] and see

+-- (IL0) in Note [Rules for instance lookup] in GHC.Core.InstEnv

+    termination. Use ``OVERLAPPING``, ``OVERLAPPABLE`` or ``OVERLAPS`` pragmas instead.

+    termination. Use ``INCOHERENT`` pragmas instead. Also permits classes to

+    have non-nominal roles, and affects the instance resolution algorithm for

+    in-scope given constraints.

+-  If there are any in-scope given constraints that might match the target

+   constraint (after unifying any metavariables), and

+   :extension:`IncoherentInstances` is not enabled, the search fails.

+

+-  If there are no candidates, the search fails.

+-  Now find all instances that *unify* with

+As an example of the "in-scope given constraints" in the first bullet,

+consider ::

+(Interested folk can read ``Note [Instance and Given overlap]`` in ``GHC.Tc.Solver.Dict``.)

+.. warning::

+     GHC's optimiser (in particular, the :ghc-flag:`-fspecialise` option)

+     assumes that type-classes are coherent, and hence it may replace

+     any type-class dictionary argument with another dictionary of the same

+     type.

+

+     This may cause unexpected results if incoherence occurs due to incoherent

+     or overlapping instances, and there is an observable difference between the

+     instances (see :ghc-ticket:`22448` and :ghc-ticket:`24924` for examples).

+

+     The :ghc-flag:`-fno-specialise-incoherents <-fspecialise-incoherents>` will

+     inhibit specialisation in the presence of some incoherent instance matches,

+     which may help avoid this issue at the cost of runtime performance.

+     Alternatively, specialisation can be disabled entirely with

+     :ghc-flag:`-fno-specialise <-fspecialise>`.

+

+-- By default -fspecialise-incoherents is in effect, so the call to m in f

+-- should get specialised even though there is another potential instance.

+

+{-# LANGUAGE UndecidableInstances #-}

+module T25833 (y) where

+

+class C a where

+  m :: a -> a

+

+instance {-# INCOHERENT #-} Num a => C a where

+  m = (* 3)

+

+instance C () where

+  m = id

+

+f :: Num a => a -> a

+f = m

+

+y :: Int

+y = f 2

+y = I# 6#

+-- Under -fno-specialise-incoherents, the call to m in f should not be

+-- specialised, because there is another possible (though unused) instance.

+

+{-# OPTIONS_GHC -fno-specialise-incoherents #-}

+{-# LANGUAGE UndecidableInstances #-}

+module T25833b (y) where

+

+class C a where

+  m :: a -> a

+

+instance {-# INCOHERENT #-} Num a => C a where

+  m = (* 3)

+

+instance C () where

+  m = id

+

+f :: Num a => a -> a

+f = m

+

+y :: Int

+y = f 2

+y = nospec m

+-- Here -fno-specialise-incoherents is in effect, but f refers unambiguously to

+-- a single instance (because there are no others), so it should be specialised.

+

+{-# OPTIONS_GHC -fno-specialise-incoherents #-}

+{-# LANGUAGE UndecidableInstances #-}

+module T25833c (y) where

+

+class C a where

+  m :: a -> a

+

+instance {-# INCOHERENT #-} Num a => C a where

+  m = (* 3)

+

+f :: Num a => a -> a

+f = m

+

+y :: Int

+y = f 2

+y = I# 6#

+{-# OPTIONS_GHC -fno-specialise-incoherents #-}

+

+module T25883d (y) where

+

+import T25883d_import

+

+instance {-# INCOHERENT #-} C () where

+  m = id

+

+f :: Num a => a -> a

+f = m

+

+y :: Int

+y = f 2

+y = I# 6#

+-- This module defines an instance with -fspecialise-incoherents in effect,

+-- then it will be imported by a module that uses -fno-specialise-incoherents.

+

+{-# LANGUAGE UndecidableInstances #-}

+module T25883d_import where

+

+class C a where

+  m :: a -> a

+

+instance {-# INCOHERENT #-} Num a => C a where

+  m = (* 3)

+

+test('T25883', normal, compile_grep_core, [''])

+test('T25883b', normal, compile_grep_core, [''])

+test('T25883c', normal, compile_grep_core, [''])

+test('T25883d', [extra_files(['T25883d_import.hs'])], multimod_compile_filter, ['T25883d', '-O -ddump-simpl -dno-typeable-binds -dsuppress-all -dsuppress-uniques', r'grep -e "y ="'])

+{-# OPTIONS_GHC -fno-specialise-incoherents #-}

+{-# LANGUAGE MonoLocalBinds #-}

+class C a where

+  op :: a -> String

+

+instance {-# OVERLAPPABLE #-} C a where

+  op _ = "C a"

+  {-# NOINLINE op #-}

+

+instance {-# INCOHERENT #-} C (Maybe a) where

+  op _ = "C (Maybe a)"

+  {-# NOINLINE op #-}

+

+instance {-# INCOHERENT #-} C (Maybe ()) where

+  op _ = "C (Maybe ())"

+  {-# NOINLINE op #-}

+

+-- | Inhibit inlining, but keep specialize-ability

+large :: a -> a

+large x = x

+{-# NOINLINE large #-}

+

+bar :: C a => a -> String

+bar x = large (large (large (large (large (large (large (large (large (large (large (large (large (large (op x))))))))))))))

+

+gen :: a -> String -- No C a constraint, has to choose the incoherent generic instance

+gen = bar

+

+specMaybe :: Maybe a -> String -- C () constraint is resolved to the specialized instance for Maybe a

+specMaybe = bar

+

+specMaybeUnit :: Maybe () -> String -- C () constraint is resolved to the specialized instance for Maybe ()

+specMaybeUnit = bar

+

+main :: IO ()

+main = do

+  putStrLn $ "gen () == " <> gen (Just ())

+  putStrLn $ "specMaybe () == " <> specMaybe (Just ())

+  putStrLn $ "specMaybeUnit () == " <> specMaybeUnit (Just ())

+gen () == C a

+specMaybe () == C (Maybe a)

+specMaybeUnit () == C (Maybe ())

+test('T23429', normal, compile_and_run, ['-O'])