>> where the underlying implementation is not known
I'm not disagreeing with the gist of what you mentioned, but this does point out that software is very complex in that the exact semantics of every interacting component has compounding effects on the overall result. This is why there is a tendency to code to achieve a pass on tests rather than by strict well defined "interface specs". However, having access to source code and working openly means problems can be identified quicker and shared quicker with other projects. If source code was not available (eg, if the library change had happened on a proprietary platform), finding the mistake would be more difficult and costly and there would be more bugs that would only come out under odd scenarios because thorough testing is impossible and certainly more difficult than analyzing even lots of source code.
An ideal wish: I want to see code assumptions be documented better on source code (assert calls and/or prose), even though we do have access to version control, peer review, and sometimes lots of testing with decent feedback. HTML can be generated from a heavily documented code to exclude all the little comments except when you want to see them (eg, before a final release or for inspection/audits). Trying to keep the source clean makes it easier to end up with problems over time. We would benefit from extensive standards for documentation, and those that like simple tools (like a simple text editor) can run simple filters on the project from the make file so that you can have all those notes not pollute a working copy.
[An extensive test suite designed to catch these problems is similar in effect but will leave holes whereas descriptive text can offer an important layer of defense.]
[Many times when you are (I am) learning a new code base, you have to make these notes anyway. Why not just formalize the effort and keep it together with the other code? We should even be able to have tests run from this documentation. Tagging precise spots can be done using any "unique" delimiter and can take an sgml approach. Then git and other tools can identify "conflicts" not just from 3-way merges with overlaps but from simple edits which overlap with a comment's scope.. triggering a requirement to update the comments whose scope were touched.]
[Another approach would be to try and keep something like a git branch of such comments/tests in sync and require that it be run before accepting commits on the main clean branch.]
[It might just be too much effort to do this in terms of bang for buck. Comments can very easily grow stale, though, that is why I suggested automatic conflict identification efforts within the workflow.]