docs: fix verified API errors in Testing Facilities section

Audit of all 35 code snippets in 7.testing pages against actual headers
revealed structural bugs that were verified by compiling and running
each example. Fixes:

* 7a thread_pool snippet: replace nonexistent <boost/capy/thread_pool.hpp>
  and pool.post(lambda) (which takes only `continuation&`) with the
  idiomatic run_async(pool.get_executor())(coroutine) pattern.

* 7b/7c/7d "Putting It Together" snippets: add missing concept-header
  includes (read_stream, read_source, write_sink, buffer_source,
  buffer_sink) so the templated examples actually compile.

* 7b/7c/7d "Putting It Together" snippets: fix a structural bug where
  mocks were constructed and asserted on outside the f.armed() lambda.
  With armed running the body multiple times for fault injection, the
  outside state was the last run's state, not the success run's. Move
  mock construction and state assertions inside the lambda following
  the canonical capy test pattern, with functions-under-test now
  returning std::error_code so callers can guard with
  `if(ec) co_return;`.

* 7c handle_request: read_source::read returns cond::eof on partial
  fill; treat eof-with-data as success rather than bailing.

* 7d buffer_sink basic example: remove the dead `if(bufs.empty())
  co_return;` check. prepare() always returns a 1-element span for a
  non-empty input array.

* All "Returns ...eof" prose and table descriptions: standardize on
  cond::eof spelling per error.hpp:32 ("Compare with cond::eof"), since
  cond::eof is the user-side comparison value while error::eof is the
  implementation's returned code. Both compare equal.

* Mock constructor signatures in tables: add `explicit` qualifier to
  match the actual headers (read_stream, write_stream, read_source,
  write_sink, buffer_source, buffer_sink, fuse(error_code)).

* Document write_some rollback semantics: write_stream::write_some and
  write_sink::write_some roll back on expected-data mismatch and return
  (test_failure, 0); call out the asymmetry with write_sink::write,
  which leaves the partial write in place.

* Expand 7a's "armed() vs. inert()" subsection with a smoke-test-first
  pattern showing the same test body under both modes, plus prose
  explaining when each fits.

* 7e bufgrind: add prose explaining why snippets use f.inert (bufgrind
  does not do I/O or consult a fuse, so a single pass is sufficient).

All snippets verified by compiling and running them through the test
suite during development.

Author: sgerbino

doc/modules/ROOT/nav.adoc

@@ -34,7 +34,7 @@
 ** xref:6.streams/6d.buffer-concepts.adoc[Buffer Sources and Sinks]
 ** xref:6.streams/6e.algorithms.adoc[Transfer Algorithms]
 ** xref:6.streams/6f.isolation.adoc[Physical Isolation]
-* xref:7.testing/7.intro.adoc[Testing Facilities]
+* xref:7.testing/7.intro.adoc[Testing]
 ** xref:7.testing/7a.drivers.adoc[Driving Tests]
 ** xref:7.testing/7b.mock-streams.adoc[Mock Streams]
 ** xref:7.testing/7c.mock-sources-sinks.adoc[Mock Sources and Sinks]

doc/modules/ROOT/pages/7.testing/7.intro.adoc

@@ -7,7 +7,7 @@
 // Official repository: https://github.com/cppalliance/capy
 //
 
-= Testing Facilities
+= Testing
 
 Real I/O is a poor foundation for unit tests. Network operations are slow,
 non-deterministic, and do not fail on demand -- so error-handling paths go

doc/modules/ROOT/pages/7.testing/7a.drivers.adoc

@@ -156,9 +156,50 @@ void test_with_fuse()
 exception mode) and is the normal choice for exhaustive error coverage.
 
 `inert()` runs the test body exactly once with no injection. Calls to
-`maybe_fail()` always return an empty error code and never throw. Use
-`inert()` when you want to verify the happy path is reachable, or when
-combining with `bufgrind` where only one run is needed.
+`maybe_fail()` always return an empty error code and never throw.
+
+Use `inert()` for happy-path verification ("does this work when nothing
+fails?"). Use `armed()` for fault-tolerance verification ("does this
+handle a failure at every async step?"). A typical test suite pairs
+both -- `inert()` confirms the function works at all, then `armed()`
+confirms it handles every error site:
+
+[source,cpp]
+----
+fuse f;
+
+// Smoke test: happy path
+auto r1 = f.inert([&](fuse&) -> task<void> {
+    read_stream rs(f);
+    rs.provide("hello");
+
+    char buf[8];
+    auto [ec, n] = co_await rs.read_some(make_buffer(buf));
+    BOOST_TEST(!ec);
+    BOOST_TEST(std::string_view(buf, n) == "hello");
+});
+BOOST_TEST(r1.success);
+
+// Fault coverage: every error site
+auto r2 = f.armed([&](fuse&) -> task<void> {
+    read_stream rs(f);
+    rs.provide("hello");
+
+    char buf[8];
+    auto [ec, n] = co_await rs.read_some(make_buffer(buf));
+    if(ec)
+        co_return;  // fuse injected an error; exit gracefully
+    BOOST_TEST(std::string_view(buf, n) == "hello");
+});
+BOOST_TEST(r2.success);
+----
+
+The only difference is the `if(ec) co_return;` guard. In `inert()`,
+that guard is dead code (`maybe_fail()` never returns an error); in
+`armed()`, it is essential.
+
+The only way to signal a test failure under `inert()` is to call
+`f.fail()` from inside the body:
 
 [source,cpp]
 ----
@@ -213,37 +254,37 @@ auto r = f.armed([&](fuse&) -> task<void> {
 BOOST_TEST(r.success);
 ----
 
-=== Dependency Injection
+=== Custom Fail Points
 
-A `fuse` constructed outside of `armed()` or `inert()` is a no-op. Passing
-it to a service at construction time lets the same service be tested without
-any code changes:
+A type that holds a `fuse` reference can call `maybe_fail()` from its own
+methods to declare additional fail points beyond those built into the
+mocks. Outside `armed()` or `inert()` the call is a no-op (returns an
+empty error code immediately); inside `armed()` it participates in
+fault injection alongside every other site.
 
 [source,cpp]
 ----
-class DataService
+class widget
 {
     fuse& f_;
 public:
-    explicit DataService(fuse& f) : f_(f) {}
+    explicit widget(fuse& f) : f_(f) {}
 
-    std::error_code fetch()
+    std::error_code process()
     {
-        auto ec = f_.maybe_fail();  // no-op in production
+        auto ec = f_.maybe_fail();
         if(ec)
             return ec;
         // ... actual work ...
         return {};
     }
 };
 
-// Production: fuse is never armed, maybe_fail() is always a no-op
 fuse f;
-DataService svc(f);
-svc.fetch();
+widget w(f);
+w.process();                                    // maybe_fail() returns {}
 
-// Tests: armed() injects failures through the same fuse
-auto r = f.armed([&](fuse&) { svc.fetch(); });
+auto r = f.armed([&](fuse&) { w.process(); });  // both branches exercised
 BOOST_TEST(r.success);
 ----
 
@@ -273,7 +314,7 @@ BOOST_TEST(r.success);
 | `fuse()`
 | Construct with the default error code (`error::test_failure`).
 
-| `fuse(std::error_code ec)`
+| `explicit fuse(std::error_code ec)`
 | Construct with a custom error code delivered by `maybe_fail()`.
 
 | `armed(fn) -> result`
@@ -330,17 +371,19 @@ Platform limits on the name length:
 
 [source,cpp]
 ----
+#include <boost/capy/ex/run_async.hpp>
+#include <boost/capy/ex/thread_pool.hpp>
+#include <boost/capy/task.hpp>
 #include <boost/capy/test/thread_name.hpp>
-#include <boost/capy/thread_pool.hpp>
 
 using namespace boost::capy;
 
 thread_pool pool(4);
-int worker = 0;
-pool.post([&] {
+run_async(pool.get_executor())([]() -> task<void> {
     set_current_thread_name("test-worker-0");
     // ... test work runs here; name appears in gdb thread list
-});
+    co_return;
+}());
 pool.join();
 ----
 

doc/modules/ROOT/pages/7.testing/7b.mock-streams.adoc

@@ -82,7 +82,7 @@ BOOST_TEST(r.success);
 === EOF Behavior
 
 When all provided data has been consumed, `read_some` returns
-`error::eof` with a byte count of zero. The stream does not
+`cond::eof` with a byte count of zero. The stream does not
 suspend; the result is available immediately.
 
 [source,cpp]
@@ -102,7 +102,7 @@ auto r = f.inert([&](fuse&) -> task<void> {
     // Second read: EOF
     auto [ec2, n2] = co_await rs.read_some(
         mutable_buffer(buf, sizeof(buf)));
-    BOOST_TEST(ec2 == error::eof);
+    BOOST_TEST(ec2 == cond::eof);
     BOOST_TEST(n2 == 0);
 });
 BOOST_TEST(r.success);
@@ -112,7 +112,7 @@ BOOST_TEST(r.success);
 |===
 | Member | Description
 
-| `read_stream(fuse f = {}, std::size_t max_read_size = std::size_t(-1))`
+| `explicit read_stream(fuse f = {}, std::size_t max_read_size = std::size_t(-1))`
 | Construct with an optional shared `fuse` and an optional per-read byte limit.
   When omitted, the fuse is inert and reads return all available data at once.
   Set `max_read_size` to simulate chunked network delivery.
@@ -123,7 +123,7 @@ BOOST_TEST(r.success);
 
 | `read_some(MutableBufferSequence buffers)`
 | Partial read. Returns up to `max_read_size` bytes (or all available
-  if no limit was set). Returns `error::eof` when the buffer is drained.
+  if no limit was set). Returns `cond::eof` when the buffer is drained.
   Consults the fuse before every read.
 
 | `available() -> std::size_t`
@@ -218,16 +218,16 @@ BOOST_TEST(r.success);
 |===
 | Member | Description
 
-| `write_stream(fuse f = {}, std::size_t max_write_size = std::size_t(-1))`
+| `explicit write_stream(fuse f = {}, std::size_t max_write_size = std::size_t(-1))`
 | Construct with an optional shared `fuse` and an optional per-write byte limit.
   When omitted, the fuse is inert and writes accept all bytes at once.
   Set `max_write_size` to simulate chunked network delivery.
 
 | `write_some(ConstBufferSequence buffers)`
 | Partial write. Appends up to `max_write_size` bytes to the internal
-  buffer. Checks against expected data after appending; returns
-  `error::test_failure` on mismatch. Consults the fuse before every
-  write.
+  buffer, then checks against the expected prefix. On mismatch, rolls
+  back the appended bytes and returns `(error::test_failure, 0)`.
+  Consults the fuse before every write.
 
 | `data() -> std::string_view`
 | Return bytes written but not yet matched by `expect()`.
@@ -300,14 +300,14 @@ operation under test.
 
 Calling `close()` on one end signals EOF to the peer. The peer drains
 any buffered data first; once the buffer is empty, subsequent
-`read_some` calls on the peer return `error::eof`. The peer may still
+`read_some` calls on the peer return `cond::eof`. The peer may still
 call `write_some` after receiving EOF.
 
 When the fuse injects an error during `read_some` or `write_some`, the
 pair is automatically closed: the calling end returns the injected
 error, any suspended reader on the other end is resumed with
-`error::eof`, and all subsequent operations on both ends return
-`error::eof`.
+`cond::eof`, and all subsequent operations on both ends return
+`cond::eof`.
 
 === Thread Safety
 
@@ -324,13 +324,13 @@ concurrent coroutines is undefined behavior.
 
 | `read_some(MutableBufferSequence buffers)`
 | Partial read from the peer's outgoing data. Suspends if no data is
-  available. Returns `error::eof` when the stream is closed or the peer
+  available. Returns `cond::eof` when the stream is closed or the peer
   called `close()`. Consults the fuse before every read (unless
   draining after `close()`).
 
 | `write_some(ConstBufferSequence buffers)`
 | Partial write into the peer's incoming buffer. Resumes a suspended
-  peer reader if any. Returns `error::eof` if the stream is closed.
+  peer reader if any. Returns `cond::eof` if the stream is closed.
   Consults the fuse before every write.
 
 | `close()`
@@ -364,17 +364,19 @@ a different error-handling branch inside `read_line`.
 
 [source,cpp]
 ----
-#include <boost/capy/test/read_stream.hpp>
-#include <boost/capy/test/fuse.hpp>
 #include <boost/capy/buffers/make_buffer.hpp>
+#include <boost/capy/concept/read_stream.hpp>
 #include <boost/capy/task.hpp>
+#include <boost/capy/test/fuse.hpp>
+#include <boost/capy/test/read_stream.hpp>
 
 using namespace boost::capy;
 using namespace boost::capy::test;
 
 // Function under test: read until '\n' or EOF
 template<ReadStream S>
-task<std::string> read_line(S& stream)
+task<std::pair<std::error_code, std::string>>
+read_line(S& stream)
 {
     std::string line;
     char ch;
@@ -383,23 +385,23 @@ task<std::string> read_line(S& stream)
         auto [ec, n] = co_await stream.read_some(
             mutable_buffer(&ch, 1));
         if(ec)
-            co_return line;
+            co_return {ec, std::move(line)};
         if(ch == '\n')
             break;
         line += ch;
     }
-    co_return line;
+    co_return {std::error_code{}, std::move(line)};
 }
 
 void test_read_line()
 {
     fuse f;
-    read_stream rs(f);
-    rs.provide("hello\n");
-
     auto r = f.armed([&](fuse&) -> task<void> {
-        auto line = co_await read_line(rs);
-        if(line.empty())
+        read_stream rs(f);
+        rs.provide("hello\n");
+
+        auto [ec, line] = co_await read_line(rs);
+        if(ec)
             co_return;  // fuse injected an error; exit gracefully
         BOOST_TEST(line == "hello");
     });