The IPv4-mapped IPv6 addresses thing is a terrible idea that ends up turned off everywhere it makes a difference. Like all of these "transition" ideas, it tries to help, but it just hurts by causing admins/ops/devs to just make sure ipv6 is off everywhere they run into it.
If all IPv6 was just opt-in everywhere, we wouldn't need all significant applications to detect and work-around broken ipv6 (in the local network, in the ISP, in the server, in the peer application). If IPv6 was only explicitly enabled, and fully consciously handled when it was, then practically everything would have opted into IPv6 years ago. As it is, things started getting IPv6 support around 2005/2006, and then disabling it around 2007/2008 because it was fake/broken ipv6 in too many places (windows teredo, 6in4, etc).
OS X had to disable IPv6 in one release and then re-enable after implementing happy-eyeballs in everything. Firefox had to do that. I know about these cases in particular, but I bet all significant network applications had to have a bunch of "detect broken IPv6" code added. Major websites had to disable IPv6 on their main domains (and sometimes added an "ipv6." subdomain). The reason was that some people had broken IPv6 and their computer would try to use it to access their site and fail (but other ipv4 only websites worked). Things are getting better now, but it was a 10 year set-back. So much time and effort could have been saved if people with good-intentions didn't add automagic transition technologies and just waited for IPv6 to be explicitly added on both ends.
So in this sense all were doomed to fail.
Remarkably the CGN devices are actually the best practical idea for this. Fake IPv4 addresses for the dumb ossified clients and that's it. If something important enough for the end user doesn't work, they'll finally upgrade.
Some US corporations did this already, rather than fuss with being "dual stack" and potentially introducing new IPv4-only services or systems, they switched wholesale to IPv6 and add converters at the edges. By choosing to do this they get most of the benefits of a future IPv6-only Internet today. For example, numbering internally is a breeze, they can auto-number almost everything because the address space is so vast there is no need to "plan" any of it.
Lots of other US corporations are still IPv4-only, indeed that's why the Google graph earlier has a distinct weekday vs weekends / holidays step change in it. At home a very large proportion of people in industrialised countries have IPv6, major ISPs supply it, common household routers understand how to use it, every modern OS groks it. But at work IPv6 is often disabled by policy, in favour of cumbersome IPv4 because that works and changing things at work is forbidden.
And it's finally starting to catch on, 10 years late: Google's primary web domains, Facebook, AWS, Comcast and Time Warner cable internet in the US, most LTE cell service in the US.
Some systems, like OpenBSD, don't even support disabling IPV6_V6ONLY and therefore don't support dual binding at all. OpenBSD contentiously argues that dual binding is likely to lead to security exploits as applications that naively bind to "::" might not expect to de-queue IPv4-mapped IPv6 addresses, consequentially possibly breaking their local access control logic. For example, they may setup firewalls rules that restrict access to the IPv6 port but forget to set the same restrictions on IPv4 ports.
I'm not sure I agree with OpenBSD's approach, but in any event applications should explicitly disable the IPV6_V6ONLY socket option if they're relying on dual binding. Ideally they should use two different sockets; one for each address family. If the application stack doesn't make it easy to listen on multiple sockets, that's a strong hint that the design is broken.
Make it work like expected.
Especially when changing infrastructure like IPV4->IPV6 - don't break existing userbase code! (This is a fundamental precept of Linux development.)
And your comment about never breaking existing userbase code is as ridiculous as it is unreasonable. This would only be a reasonable expectation if only correct code were possible to run. Since it's possible to run broken code (as this anecdote demonstrates) then it must be possible to fix the system even if that breaks some poorly written, but popular systems.
Does anyone want a world of e.g. Windows where decades old bugs have to be replicated because we can't dare break programs so old all the authors are retired or dead? I don't. Backwards compatibility has a cost and I'm not willing to pay it unconditionally.
Expected by code or by the progammer(s)?
That said, strong API guarantees are the way, documentation should note the bug, introduce a fixed version for the API, maybe schedule deprecation in 10-15 years, and carry on with life.
It's not worth it to hunt down every client and make them fix your honest mistake.
If you're on a POSIX system, I'd argue that this is a bug in the client. Typically, the client should call getaddrinfo(3); as part of that, the application would either specify directly that it's only interested in AF_INET results, or just filter out non-AF_INET results.
(Further, if you support IPv6 in the client, and thus request such results from getaddrinfo, you should skip to the next result if the connection fails.)
On the server, you can also bind to both the IPv4 and the IPv6 addresses. If you listen to ::, you should get IPv4 connections too. (Through this[1] mechanism.)
[1]: https://en.wikipedia.org/wiki/IPv6_address#Transition_from_I...