| ... | ... | @@ -1098,7 +1098,7 @@ There are two ways in which decomposing (N ty1) ~r (N ty2) could be incomplete: | 
| 1098 | 1098 |    them.  This is done in can_eq_nc.  Of course, we can't unwrap if the data
 | 
| 1099 | 1099 |    constructor isn't in scope.  See Note [Unwrap newtypes first].
 | 
| 1100 | 1100 |  
 | 
| 1101 |  | -* Incompleteness example (EX2): see #24887
 | 
|  | 1101 | +* Incompleteness example (EX2): prioritise Nominal equalities. See #24887
 | 
| 1102 | 1102 |        data family D a
 | 
| 1103 | 1103 |        data instance D Int  = MkD1 (D Char)
 | 
| 1104 | 1104 |        data instance D Bool = MkD2 (D Char)
 | 
| ... | ... | @@ -1116,7 +1116,7 @@ There are two ways in which decomposing (N ty1) ~r (N ty2) could be incomplete: | 
| 1116 | 1116 |    CONCLUSION: prioritise nominal equalites in the work list.
 | 
| 1117 | 1117 |    See Note [Prioritise equalities] in GHC.Tc.Solver.InertSet.
 | 
| 1118 | 1118 |  
 | 
| 1119 |  | -* Incompleteness example (EX3): available Givens
 | 
|  | 1119 | +* Incompleteness example (EX3): check available Givens
 | 
| 1120 | 1120 |        newtype Nt a = Mk Bool         -- NB: a is not used in the RHS,
 | 
| 1121 | 1121 |        type role Nt representational  -- but the user gives it an R role anyway
 | 
| 1122 | 1122 |  
 | 
| ... | ... | @@ -1134,36 +1134,41 @@ There are two ways in which decomposing (N ty1) ~r (N ty2) could be incomplete: | 
| 1134 | 1134 |    equalities that could later solve it.
 | 
| 1135 | 1135 |  
 | 
| 1136 | 1136 |    But what precisely does it mean to say "any Given equalities that could
 | 
| 1137 |  | -  later solve it"?
 | 
| 1138 |  | -
 | 
| 1139 |  | -  In #22924 we had
 | 
| 1140 |  | -     [G] f a ~R# a     [W] Const (f a) a ~R# Const a a
 | 
| 1141 |  | -  where Const is an abstract newtype.  If we decomposed the newtype, we
 | 
| 1142 |  | -  could solve.  Not-decomposing on the grounds that (f a ~R# a) might turn
 | 
| 1143 |  | -  into (Const (f a) a ~R# Const a a) seems a bit silly.
 | 
| 1144 |  | -
 | 
| 1145 |  | -  In #22331 we had
 | 
| 1146 |  | -     [G] N a ~R# N b   [W] N b ~R# N a
 | 
| 1147 |  | -  (where N is abstract so we can't unwrap). Here we really /don't/ want to
 | 
| 1148 |  | -  decompose, because the /only/ way to solve the Wanted is from that Given
 | 
| 1149 |  | -  (with a Sym).
 | 
| 1150 |  | -
 | 
| 1151 |  | -  In #22519 we had
 | 
| 1152 |  | -     [G] a <= b     [W] IO Age ~R# IO Int
 | 
| 1153 |  | -
 | 
| 1154 |  | -  (where IO is abstract so we can't unwrap, and newtype Age = Int; and (<=)
 | 
| 1155 |  | -  is a type-level comparison on Nats).  Here we /must/ decompose, despite the
 | 
| 1156 |  | -  existence of an Irred Given, or we will simply be stuck.  (Side note: We
 | 
| 1157 |  | -  flirted with deep-rewriting of newtypes (see discussion on #22519 and
 | 
| 1158 |  | -  !9623) but that turned out not to solve #22924, and also makes type
 | 
| 1159 |  | -  inference loop more often on recursive newtypes.)
 | 
|  | 1137 | +  later solve it"?  It's tricky!
 | 
|  | 1138 | +
 | 
|  | 1139 | +  * In #22924 we had
 | 
|  | 1140 | +       [G] f a ~R# a     [W] Const (f a) a ~R# Const a a
 | 
|  | 1141 | +    where Const is an abstract newtype.  If we decomposed the newtype, we
 | 
|  | 1142 | +    could solve.  Not-decomposing on the grounds that (f a ~R# a) might turn
 | 
|  | 1143 | +    into (Const (f a) a ~R# Const a a) seems a bit silly.
 | 
|  | 1144 | +
 | 
|  | 1145 | +  * In #22331 we had
 | 
|  | 1146 | +       [G] N a ~R# N b   [W] N b ~R# N a
 | 
|  | 1147 | +    (where N is abstract so we can't unwrap). Here we really /don't/ want to
 | 
|  | 1148 | +    decompose, because the /only/ way to solve the Wanted is from that Given
 | 
|  | 1149 | +    (with a Sym).
 | 
|  | 1150 | +
 | 
|  | 1151 | +  * In #22519 we had
 | 
|  | 1152 | +       [G] a <= b     [W] IO Age ~R# IO Int
 | 
|  | 1153 | +
 | 
|  | 1154 | +    (where IO is abstract so we can't unwrap, and newtype Age = Int; and (<=)
 | 
|  | 1155 | +    is a type-level comparison on Nats).  Here we /must/ decompose, despite the
 | 
|  | 1156 | +    existence of an Irred Given, or we will simply be stuck.  (Side note: We
 | 
|  | 1157 | +    flirted with deep-rewriting of newtypes (see discussion on #22519 and
 | 
|  | 1158 | +    !9623) but that turned out not to solve #22924, and also makes type
 | 
|  | 1159 | +    inference loop more often on recursive newtypes.)
 | 
|  | 1160 | +
 | 
|  | 1161 | +  * In #26020 we had a /quantified/ constraint
 | 
|  | 1162 | +        forall x. Coercible (N t1) (N t2)
 | 
|  | 1163 | +    and (roughly) [W] N t1 ~R# N t2
 | 
|  | 1164 | +    That quantified constraint can solve the Wanted, so don't decompose!
 | 
| 1160 | 1165 |  
 | 
| 1161 | 1166 |    The currently-implemented compromise is this:
 | 
| 1162 |  | -
 | 
| 1163 |  | -    we decompose [W] N s ~R# N t unless there is a [G] N s' ~ N t'
 | 
| 1164 |  | -
 | 
| 1165 |  | -  that is, a Given Irred equality with both sides headed with N.
 | 
| 1166 |  | -  See the call to noGivenNewtypeReprEqs in canTyConApp.
 | 
|  | 1167 | +       We decompose [W] N s ~R# N t unless there is
 | 
|  | 1168 | +       - an Irred [G] N s' ~ N t'
 | 
|  | 1169 | +       - a quantified [G] forall ... => N s' ~ N t'
 | 
|  | 1170 | +       that is, a Given equality with both sides headed with N.
 | 
|  | 1171 | +  See the call to `noGivenNewtypeReprEqs` in `canTyConApp`.
 | 
| 1167 | 1172 |  
 | 
| 1168 | 1173 |    This is not perfect.  In principle a Given like [G] (a b) ~ (c d), or
 | 
| 1169 | 1174 |    even just [G] c, could later turn into N s ~ N t.  But since the free
 | 
| ... | ... | @@ -1174,7 +1179,7 @@ There are two ways in which decomposing (N ty1) ~r (N ty2) could be incomplete: | 
| 1174 | 1179 |    un-expanded equality superclasses; but only in some very obscure
 | 
| 1175 | 1180 |    recursive-superclass situations.
 | 
| 1176 | 1181 |  
 | 
| 1177 |  | -   Yet another approach (!) is desribed in
 | 
|  | 1182 | +   Yet another approach (!) is described in
 | 
| 1178 | 1183 |     Note [Decomposing newtypes a bit more aggressively].
 | 
| 1179 | 1184 |  
 | 
| 1180 | 1185 |  Remember: decomposing Wanteds is always /sound/. This Note is
 |