New iterate interface and type stability

I have a general question about the new iterate interface: it seems that it is inherently type unstable. What I understand from various posts on this topic is that the introduction of the new interface is accompanied with a new and improved optimiser that can build in all practical situations code that does not suffer from this semantics level type instability.

I do wonder however whether this changes the contract with the user of Julia. Before 0.7 the rule was: write type stable code and you will get near c performance. Is this rule of thumb now changing to something more complicated? Something like: Write code that our optimiser - which is a very complicated algorithm sitting inside an opaque box - can deal with, and you get near c performance? Or are there well defined mild cases of type instability that are allowed, and now even encouraged?

It boils down to Julia now effectively handling small type unions, which (if I recall correctly) had to be extended to nested unions to make the new iterator work. Maybe there is a doc entry for this in the latest docs? Otherwise there probably should be.

I would instead say that it has changed from “write type stable code and you will get near c performance” to “write type stable code and you will get near c performance, but if you return small unions that is usually fine too”

Is there some documentation on this somewhere. As long as it is deterministic and documented one can rely on this as a user.