document what happens in case of errors

I would like to know when `BufWriter::shutdown()` or `flush()` fail whether the write has partially succeeded. Ideally I'd like to have a way to upload such that the operation will be atomic, and the file will not end up in a partially-uploaded state.

Specifically, I'd like to have documented what the consequences of an error in `flush` or `shutdown` are.

Start by locating the BufWriter::flush() and BufWriter::shutdown() entry points and the existing object-store documentation around uploads. Determine and document what users can expect when either operation returns an error, including whether partial writes are possible and whether atomic upload is supported. Done means the documented consequences and atomicity limitations are clear.

Written by the indexing model from the issue text.