Error provenance — identify which stream an error originated from

[sgerbino]

Summary

When an error is reported there is no way to figure out which stream it
originated from. The author accepted this should be fixed.

Detail

When an error is reported there is no way to figure out from which stream it
originated. This makes debugging and error handling harder in code that manages
multiple streams.

Acceptance criteria

• A way to attribute a reported error to the originating stream.

References

Distinct from #298 (error dispositions).

Raised by Andrzej Krzemienski; Steve Gerbino agreed ("you're right about this
and we should fix it"). Source: Boost ML "[capy] error codes".

[akrzemi1]

The title of this issue is very generic, not specific to the pumping functions, so let me make use of this genericity.

Sometimes error_code specifies the status of the stream. But sometimes it is just used to signal a precondition violation: https://github.com/cppalliance/capy/blob/develop-2/include/boost/capy/read_at_least.hpp#L113

There is no consistency or clear picture what these error_code are used for.