Align read_some/write_some to E2 semantics and add exception docs

Adopt the relaxed error postcondition (n >= 0 on error) from the
read-some-rationale consensus throughout headers, implementation,
docs, examples, and papers. Fix composed algorithms (read, write,
write_now, push_to) to use advance-then-check ordering. Replace
.failed() with operator bool() idiom. Add error reporting and
throws documentation to all concept Javadocs and the rationale doc.
Introduce await-returns terminology per stakeholder feedback. Use
C++ expressions for range constraints. Remove if(n > 0) guards
from echo loops in favor of unconditional write-then-check pattern.

Author: sgerbino

doc/modules/ROOT/pages/5.buffers/5c.sequences.adoc

@@ -117,10 +117,10 @@ task<std::size_t> read_all(Stream& stream, Buffers buffers)
     while (buffer_size(remaining) > 0)
     {
         auto [ec, n] = co_await stream.read_some(remaining);
-        if (ec.failed())
-            break;
         remaining.consume(n);
         total += n;
+        if (ec)
+            break;
     }
     
     co_return total;

doc/modules/ROOT/pages/5.buffers/5e.algorithms.adoc

@@ -157,11 +157,10 @@ task<std::size_t> read_full(Stream& stream, Buffers buffers)
     while (buffer_size(remaining) > 0)
     {
         auto [ec, n] = co_await stream.read_some(remaining);
-        if (ec.failed())
-            co_return total;  // Return partial read on error
-        
         remaining.consume(n);
         total += n;
+        if (ec)
+            co_return total;
     }
     
     co_return total;
@@ -181,11 +180,10 @@ task<std::size_t> write_full(Stream& stream, Buffers buffers)
     while (buffer_size(remaining) > 0)
     {
         auto [ec, n] = co_await stream.write_some(remaining);
-        if (ec.failed())
-            co_return total;
-        
         remaining.consume(n);
         total += n;
+        if (ec)
+            co_return total;
     }
     
     co_return total;

doc/modules/ROOT/pages/5.buffers/5f.dynamic.adoc

@@ -76,9 +76,8 @@ task<> read_into_buffer(Stream& stream, DynamicBuffer auto& buffer)
     
     // Read into prepared space
     auto [ec, n] = co_await stream.read_some(space);
-    
-    if (!ec.failed())
-        buffer.commit(n);  // Make data readable
+
+    buffer.commit(n);  // Make data readable
 }
 ----
 
@@ -240,9 +239,9 @@ task<std::string> read_line(Stream& stream)
         // Prepare space and read
         auto space = buffer.prepare(256);
         auto [ec, n] = co_await stream.read_some(space);
-        if (ec.failed())
-            throw std::system_error(ec);
         buffer.commit(n);
+        if (ec)
+            throw std::system_error(ec);
         
         // Search for newline in readable data
         auto data = buffer.data();

doc/modules/ROOT/pages/6.streams/6a.overview.adoc

@@ -167,10 +167,12 @@ task<> echo(any_stream& stream)
     for (;;)
     {
         auto [ec, n] = co_await stream.read_some(mutable_buffer(buf));
+
+        auto [wec, wn] = co_await write(stream, const_buffer(buf, n));
+
         if (ec)
             co_return;
-        
-        auto [wec, wn] = co_await write(stream, const_buffer(buf, n));
+
         if (wec)
             co_return;
     }

doc/modules/ROOT/pages/6.streams/6b.streams.adoc

@@ -28,13 +28,18 @@ template<MutableBufferSequence Buffers>
 IoAwaitable auto read_some(Buffers buffers);
 ----
 
-Returns an awaitable yielding `(error_code, std::size_t)`:
+Attempts to read up to `buffer_size(buffers)` bytes from the stream into the buffer sequence. Await-returns `(error_code, std::size_t)`:
 
-* On success: `!ec`, and `n >= 1` bytes were read
-* On error: `ec`, and `n == 0`
-* On EOF: `ec == cond::eof`, and `n == 0`
+If `buffer_size(buffers) > 0`:
 
-If `buffer_empty(buffers)` is true, completes immediately with `n == 0` and no error.
+* If `!ec`, then `n >= 1 && n \<= buffer_size(buffers)`. `n` bytes were read into the buffer sequence.
+* If `ec`, then `n >= 0 && n \<= buffer_size(buffers)`. `n` is the number of bytes read before the I/O condition arose.
+
+If `buffer_empty(buffers)` is true, `n` is 0. The empty buffer is not itself a cause for error, but `ec` may reflect the state of the stream.
+
+I/O conditions from the underlying system are reported via `ec`. Failures in the library itself (such as allocation failure) are reported via exceptions.
+
+*Throws:* `std::bad_alloc` if coroutine frame allocation fails.
 
 === Partial Transfer
 
@@ -45,7 +50,7 @@ If `buffer_empty(buffers)` is true, completes immediately with `n == 0` and no e
 char buf[1024];
 auto [ec, n] = co_await stream.read_some(mutable_buffer(buf));
 // n might be 1, might be 500, might be 1024
-// The only guarantee: if !ec && n > 0
+// if !ec, then n >= 1
 ----
 
 This matches underlying OS behavior—reads return when *some* data is available.
@@ -58,18 +63,15 @@ template<ReadStream Stream>
 task<> dump_stream(Stream& stream)
 {
     char buf[256];
-    
+
     for (;;)
     {
         auto [ec, n] = co_await stream.read_some(mutable_buffer(buf));
-        
-        if (ec == cond::eof)
-            break;  // End of stream
-        
-        if (ec)
-            throw std::system_error(ec);
-        
+
         std::cout.write(buf, n);
+
+        if (ec)
+            break;
     }
 }
 ----
@@ -95,12 +97,18 @@ template<ConstBufferSequence Buffers>
 IoAwaitable auto write_some(Buffers buffers);
 ----
 
-Returns an awaitable yielding `(error_code, std::size_t)`:
+Attempts to write up to `buffer_size(buffers)` bytes from the buffer sequence to the stream. Await-returns `(error_code, std::size_t)`:
 
-* On success: `!ec`, and `n >= 1` bytes were written
-* On error: `ec`, and `n == 0`
+If `buffer_size(buffers) > 0`:
 
-If `buffer_empty(buffers)` is true, completes immediately with `n == 0` and no error.
+* If `!ec`, then `n >= 1 && n \<= buffer_size(buffers)`. `n` bytes were written from the buffer sequence.
+* If `ec`, then `n >= 0 && n \<= buffer_size(buffers)`. `n` is the number of bytes written before the I/O condition arose.
+
+If `buffer_empty(buffers)` is true, `n` is 0. The empty buffer is not itself a cause for error, but `ec` may reflect the state of the stream.
+
+I/O conditions from the underlying system are reported via `ec`. Failures in the library itself (such as allocation failure) are reported via exceptions.
+
+*Throws:* `std::bad_alloc` if coroutine frame allocation fails.
 
 === Partial Transfer
 
@@ -191,20 +199,15 @@ task<> handle_connection(any_stream& stream)
     
     for (;;)
     {
-        // Read some data
         auto [ec, n] = co_await stream.read_some(mutable_buffer(buf));
-        
-        if (ec == cond::eof)
-            co_return;  // Client closed connection
-        
-        if (ec)
-            throw std::system_error(ec);
-        
-        // Echo it back
+
         auto [wec, wn] = co_await write(stream, const_buffer(buf, n));
-        
+
+        if (ec)
+            break;
+
         if (wec)
-            throw std::system_error(wec);
+            break;
     }
 }
 ----

doc/modules/ROOT/pages/6.streams/6c.sources-sinks.adoc

@@ -29,7 +29,7 @@ template<MutableBufferSequence Buffers>
 IoAwaitable auto read(Buffers buffers);
 ----
 
-Returns an awaitable yielding `(error_code, std::size_t)`:
+Await-returns `(error_code, std::size_t)`:
 
 * On success: `!ec`, and `n == buffer_size(buffers)` (buffer completely filled)
 * On EOF: `ec == cond::eof`, and `n` is bytes read before EOF (partial read)

doc/modules/ROOT/pages/6.streams/6d.buffer-concepts.adoc

@@ -52,11 +52,11 @@ concept BufferSource =
 IoAwaitable auto pull(const_buffer* arr, std::size_t max_count);
 ----
 
-Returns an awaitable yielding `(error_code, std::size_t)`:
+Await-returns `(error_code, std::size_t)`:
 
-* On success: `!ec.failed()`, fills `arr[0..count-1]` with buffer descriptors
+* On success: `!ec`, fills `arr[0..count-1]` with buffer descriptors
 * On exhausted: `count == 0` indicates no more data
-* On error: `ec.failed()`
+* On error: `ec`
 
 The buffers point into the source's internal storage. You must consume all returned data before calling `pull()` again—the previous buffers become invalid.
 
@@ -73,7 +73,7 @@ task<> process_source(Source& source)
     {
         auto [ec, count] = co_await source.pull(bufs, 8);
         
-        if (ec.failed())
+        if (ec)
             throw std::system_error(ec);
         
         if (count == 0)
@@ -228,7 +228,7 @@ task<> decompress_stream(any_buffer_source& compressed, any_write_sink& output)
     for (;;)
     {
         auto [ec, count] = co_await compressed.pull(bufs, 8);
-        if (ec.failed())
+        if (ec)
             throw std::system_error(ec);
         if (count == 0)
             break;

doc/modules/ROOT/pages/6.streams/6e.algorithms.adoc

@@ -224,7 +224,7 @@ if (ec == cond::eof)
     // Normal completion
     std::cout << "Transferred " << total << " bytes\n";
 }
-else if (ec.failed())
+else if (ec)
 {
     // Error occurred
     std::cerr << "Error after " << total << " bytes: " << ec.message() << "\n";

doc/modules/ROOT/pages/6.streams/6f.isolation.adoc

@@ -38,7 +38,7 @@ task<> handle_protocol(any_stream& stream)
     for (;;)
     {
         auto [ec, n] = co_await stream.read_some(mutable_buffer(buf));
-        if (ec.failed())
+        if (ec)
             co_return;
         
         // Process and respond...

doc/modules/ROOT/pages/7.examples/7d.mock-stream-testing.adoc

@@ -41,17 +41,19 @@ capy::task<bool> echo_line_uppercase(capy::any_stream& stream)
         // ec: std::error_code, n: std::size_t
         auto [ec, n] = co_await stream.read_some(capy::mutable_buffer(&c, 1));
 
+        if (n > 0)
+        {
+            if (c == '\n')
+                break;
+            line += static_cast<char>(std::toupper(static_cast<unsigned char>(c)));
+        }
+
         if (ec)
         {
             if (ec == capy::cond::eof)
                 break;
             co_return false;
         }
-        
-        if (c == '\n')
-            break;
-        
-        line += static_cast<char>(std::toupper(static_cast<unsigned char>(c)));
     }
     
     line += '\n';
@@ -63,11 +65,11 @@ capy::task<bool> echo_line_uppercase(capy::any_stream& stream)
         // wec: std::error_code, wn: std::size_t
         auto [wec, wn] = co_await stream.write_some(
             capy::const_buffer(line.data() + written, line.size() - written));
-        
+
+        written += wn;
+
         if (wec)
             co_return false;
-        
-        written += wn;
     }
     
     co_return true;