more fixes to doc

Signed-off-by: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com>

Author: pratikmankawde

BoostToStdCoroutineSwitchPlan.md

@@ -34,8 +34,6 @@ This document describes the plan for migrating rippled's coroutine implementatio
 
 Coroutines in rippled are used to handle long-running RPC requests — such as pathfinding — without blocking server threads. When a request needs to wait for an external event, the coroutine **suspends** (freeing the thread for other work) and **resumes** later when the event completes.
 
-**In simple terms:** Think of a restaurant kitchen. The current system (Boost.Coroutine) is like giving each order its own dedicated chef who stands idle while waiting for the oven — expensive in staff. The new system (C++20 coroutines) is like giving each order a ticket: the chef puts the ticket aside when waiting for the oven, picks up another order, and returns to the first ticket when the oven beeps. Same kitchen, far fewer idle chefs.
-
 ---
 
 ## 2. Why Is This Needed?
@@ -145,14 +143,14 @@ graph LR
 
 ### 4.3 Performance Characteristics
 
-| Metric                         | Boost.Coroutine2                                                     | C++20 Coroutines                     |
-| ------------------------------ | -------------------------------------------------------------------- | ------------------------------------ |
-| **Memory per coroutine**       | ~1.5 MB (fixed stack)                                                | ~200-500 bytes (frame only)          |
-| **1000 concurrent coroutines** | ~1.5 GB                                                              | ~0.5 MB                              |
-| **Context switch cost**        | ~19 CPU cycles (fcontext save/restore, per Boost.Context benchmarks) | ~20-50 CPU cycles (function call)    |
-| **Allocation**                 | Stack allocated at creation                                          | Heap allocation (compiler may elide) |
-| **Cache behavior**             | Poor (large stack rarely fully used)                                 | Good (small frame, hot data close)   |
-| **Compiler optimization**      | Opaque to compiler                                                   | Inlinable, optimizable               |
+| Metric                         | Boost.Coroutine2                                                                         | C++20 Coroutines                     |
+| ------------------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------ |
+| **Memory per coroutine**       | ~1.5 MB (fixed stack)                                                                    | ~200-500 bytes (frame only)          |
+| **1000 concurrent coroutines** | ~1.5 GB                                                                                  | ~0.5 MB                              |
+| **Context switch cost**        | ~19 cycles / 9 ns with fcontext; ~1,130 cycles / 547 ns with ucontext (ASAN/TSAN builds) | ~20-50 CPU cycles (function call)    |
+| **Allocation**                 | Stack allocated at creation                                                              | Heap allocation (compiler may elide) |
+| **Cache behavior**             | Poor (large stack rarely fully used)                                                     | Good (small frame, hot data close)   |
+| **Compiler optimization**      | Opaque to compiler                                                                       | Inlinable, optimizable               |
 
 ### 4.4 Feature Parity Analysis
 
@@ -233,9 +231,17 @@ However, these types are small, well-understood, and have extensive reference im
 
 **Claim**: If coroutine A `co_await`s coroutine B, and B completes synchronously, B's `final_suspend` resumes A on the same stack, potentially building up unbounded stack depth.
 
-**Analysis**: This is addressed by **symmetric transfer** via `FinalAwaiter::await_suspend()` returning a `coroutine_handle<>` instead of `void`. The compiler transforms this into a tail-call, preventing stack growth. This is the standard solution used by all major coroutine libraries and is implemented in our `FinalAwaiter` design (Section 7.1).
+**Why this is a real problem without symmetric transfer**: When `await_suspend()` returns `void`, the coroutine unconditionally suspends and returns from `.resume()`. If the awaited coroutine completes synchronously and calls `.resume()` on the awaiter, each such call adds a stack frame. In a loop that repeatedly `co_await`s short-lived coroutines (e.g., a generator producing millions of values), the stack grows with each iteration until it overflows — typically after ~1M iterations.
+
+**How symmetric transfer solves it**: When `await_suspend()` returns a `coroutine_handle<>` instead of `void`, the compiler destroys the current coroutine's stack frame _before_ jumping to the returned handle. This is effectively a tail-call: `resume()` becomes a `jmp` instead of a `call`, so each chained resumption consumes **zero additional stack space**.
+
+The C++ standard (P0913R0) mandates this by requiring: _"Implementations shall not impose any limits on how many coroutines can be resumed in this fashion."_ This effectively requires compilers to implement tail-call-like behavior — any finite stack would impose a limit otherwise.
 
-**Verdict**: Solved by symmetric transfer (already in our design).
+**Returning `std::noop_coroutine()`** from `await_suspend()` signals "suspend and return to caller" without resuming another coroutine, serving the role that `void` return used to play.
+
+**Applicability to rippled**: rippled does not chain coroutines (coroutine A awaiting coroutine B). The `co_await` points in rippled await `JobQueueAwaiter` (reschedules on the thread pool) and `yieldAndPost()` (suspend + re-post), both of which always suspend asynchronously. However, symmetric transfer is still implemented in our `FinalAwaiter` ([Section 7.1](#71-new-type-design)) as a best practice — it costs nothing and prevents stack overflow if the usage pattern ever changes.
+
+**Verdict**: Real concern for coroutine chains, but does not affect rippled's current usage. Solved by symmetric transfer in our design regardless.
 
 #### **Concern 5: Dangling Reference Risk**
 
@@ -271,7 +277,7 @@ However, these types are small, well-understood, and have extensive reference im
 
 **Verdict**: Separate system. Out of scope for this migration.
 
-**Consequence — `Boost::context` dependency is retained**: Because `boost::asio::spawn` depends on `Boost.Context` for its stackful fiber implementation, the `Boost::context` library **cannot be removed** as part of this migration. The CMake cleanup (Phase 4) replaces `Boost::coroutine` with `Boost::context` — it does not eliminate the Boost fiber dependency entirely.
+**Consequence — `Boost::context` dependency is retained**: Because `boost::asio::spawn` depends on `Boost.Context` for its stackful fiber implementation, the `Boost::context` library **cannot be removed** as part of this migration. The CMake cleanup ([Phase 4](#phase-4-cleanup)) replaces `Boost::coroutine` with `Boost::context` — it does not eliminate the Boost fiber dependency entirely.
 
 Additionally, when running under ASAN or TSAN, `Boost.Context` must be built with the `ucontext` backend (not the default `fcontext`) so that it emits `__sanitizer_start_switch_fiber` / `__sanitizer_finish_switch_fiber` annotations during fiber context switches. Without these annotations, the sanitizers cannot track memory ownership across fiber stack switches and will report false positives (stack-use-after-scope under ASAN, data races under TSAN) for the `boost::asio::spawn` call sites listed above. This requires:
 
@@ -342,7 +348,7 @@ graph TD
     end
 
     subgraph "Coroutine Layer"
-        POST["JobQueue::postCoro()<br/>Creates Coro + schedules job"]
+        POST["JobQueue::postCoro()<br/>Creates Coro<br/>+ schedules job"]
         CORO["JobQueue::Coro<br/>boost::coroutines2::coroutine<void>::pull_type<br/>1.5 MB stack per instance"]
     end
 
@@ -563,8 +569,6 @@ rippled **already uses C++20 coroutines** in test code:
 
 ## 6. Migration Strategy
 
-> **RPC** = Remote Procedure Call | **API** = Application Programming Interface
-
 ### 6.1 Incremental vs Atomic Migration
 
 **Decision: Incremental (multi-phase) migration.**
@@ -580,15 +584,15 @@ Rationale:
 
 ```mermaid
 graph TD
-    subgraph "Phase 1: Foundation"
+    subgraph PH1 ["Phase 1: Foundation"]
         P1A["Create CoroTask#lt;T#gt; type<br/>(promise_type, awaiter)"]
         P1B["Create JobQueueAwaiter<br/>(schedules resume on JobQueue)"]
         P1C["Add postCoroTask() to JobQueue<br/>(parallel to postCoro)"]
         P1D["Unit tests for new primitives"]
         P1A --> P1B --> P1C --> P1D
     end
 
-    subgraph "Phase 2: Entry Point Migration"
+    subgraph PH2 ["Phase 2: Entry Point Migration"]
         P2A["Migrate ServerHandler::onRequest()"]
         P2B["Migrate ServerHandler::onWSMessage()"]
         P2C["Migrate GRPCServer::CallData::process()"]
@@ -598,32 +602,31 @@ graph TD
         P2C --> P2D
     end
 
-    subgraph "Phase 3: Handler Migration"
+    subgraph PH3 ["Phase 3: Handler Migration"]
         P3A["Migrate RipplePathFind handler"]
         P3B["Verify all other handlers<br/>(no active yield usage)"]
     end
 
-    subgraph "Phase 4: Cleanup"
+    subgraph PH4 ["Phase 4: Cleanup"]
         P4A["Remove old Coro class"]
         P4B["Remove Boost.Coroutine from CMake"]
         P4C["Remove deprecation warning suppression"]
         P4D["Final benchmarks & validation"]
+        P4A --> P4B --> P4C --> P4D
     end
 
-    P1D --> P2A
-    P2D --> P3A
-    P3B --> P4A
-    P3A --> P4A
-    P4A --> P4B --> P4C --> P4D
+    PH1 --> PH2
+    PH2 --> PH3
+    PH3 --> PH4
 ```
 
 **Reading the diagram:**
 
-- **Phase 1** builds the new coroutine primitives (`CoroTask`, `JobQueueAwaiter`, `postCoroTask()`) alongside the existing Boost code. No production code changes.
-- **Phase 2** migrates the three entry points (HTTP, WebSocket, gRPC) to use `postCoroTask()` and updates `RPC::Context`.
-- **Phase 3** migrates the `RipplePathFind` handler and verifies no other handlers use `yield()`.
-- **Phase 4** removes the old `Coro` class, `Coro.ipp`, `Boost::coroutine` from CMake, and runs final benchmarks.
-- Each phase depends on the previous one completing. The old code is not deleted until Phase 4, so rollback is safe through Phases 1–3.
+- **[Phase 1](#phase-1-new-coroutine-primitives)** builds the new coroutine primitives (`CoroTask`, `JobQueueAwaiter`, `postCoroTask()`) alongside the existing Boost code. No production code changes.
+- **[Phase 2](#phase-2-entry-point-migration)** migrates the three entry points (HTTP, WebSocket, gRPC) to use `postCoroTask()` and updates `RPC::Context`.
+- **[Phase 3](#phase-3-handler-migration)** migrates the `RipplePathFind` handler and verifies no other handlers use `yield()`.
+- **[Phase 4](#phase-4-cleanup)** removes the old `Coro` class, `Coro.ipp`, `Boost::coroutine` from CMake, and runs final benchmarks.
+- Each phase depends on the previous one completing. The old code is not deleted until [Phase 4](#phase-4-cleanup), so rollback is safe through Phases 1–3.
 
 ### 6.3 Coexistence Strategy
 
@@ -651,12 +654,12 @@ graph LR
 
 ### 6.4 Breaking Changes & Compatibility
 
-| Concern                          | Impact                                    | Mitigation                                               |
-| -------------------------------- | ----------------------------------------- | -------------------------------------------------------- |
-| `RPC::Context::coro` type change | All RPC handlers receive context          | Migrate context field last, after all consumers updated  |
-| `postCoro()` removal             | 3 callers                                 | Replace with `postCoroTask()`, remove old API in Phase 4 |
-| `LocalValue` integration         | Thread-local storage must work            | New implementation must swap LocalValues identically     |
-| Shutdown behavior                | `expectEarlyExit()`, `nSuspend_` tracking | Replicate in new CoroTask                                |
+| Concern                          | Impact                                    | Mitigation                                                                   |
+| -------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------- |
+| `RPC::Context::coro` type change | All RPC handlers receive context          | Migrate context field last, after all consumers updated                      |
+| `postCoro()` removal             | 3 callers                                 | Replace with `postCoroTask()`, remove old API in [Phase 4](#phase-4-cleanup) |
+| `LocalValue` integration         | Thread-local storage must work            | New implementation must swap LocalValues identically                         |
+| Shutdown behavior                | `expectEarlyExit()`, `nSuspend_` tracking | Replicate in new CoroTask                                                    |
 
 ---
 
@@ -1060,21 +1063,21 @@ quadrantChart
     Third-party Boost dep: [0.10, 0.30]
 ```
 
-| Risk                                                  | Probability | Impact | Mitigation                                                                  |
-| ----------------------------------------------------- | ----------- | ------ | --------------------------------------------------------------------------- |
-| **Performance regression** in context switching       | Low         | High   | Benchmark before/after; C++20 should be faster                              |
-| **Coroutine frame lifetime bugs** (use-after-destroy) | Medium      | High   | ASAN testing, RAII wrapper for handle, code review                          |
-| **Data races on resume**                              | Medium      | High   | TSAN testing, careful await_suspend() implementation                        |
-| **LocalValue corruption** across threads              | Low         | High   | Dedicated test with 4+ concurrent coroutines                                |
-| **Shutdown race conditions**                          | Medium      | Medium | Replicate existing mutex/cv pattern in new design                           |
-| **Missed coroutine consumer** during migration        | Low         | Medium | Exhaustive grep audit (Section 5.4 is complete)                             |
-| **Compiler bugs** in coroutine codegen                | Low         | Medium | Test on all three compilers (GCC, Clang, MSVC)                              |
-| **Exception loss** across suspension points           | Medium      | Medium | Test exception propagation in every phase                                   |
-| **Third-party code depending on Boost.Coroutine**     | Very Low    | Low    | Grep confirms only internal usage                                           |
-| **Dangling references in coroutine frames**           | Medium      | High   | ASAN testing, avoid reference params in coroutine functions, use shared_ptr |
-| **Colored function infection spreading**              | Low         | Medium | Only 4 call sites need co_await; no nested handlers suspend                 |
-| **Symmetric transfer not available**                  | Very Low    | High   | All target compilers (GCC 12+, Clang 16+) support symmetric transfer        |
-| **Future handler adding deep yield**                  | Low         | Medium | Code review + CI: static analysis flag any yield from nested depth          |
+| Risk                                                  | Probability | Impact | Mitigation                                                                       |
+| ----------------------------------------------------- | ----------- | ------ | -------------------------------------------------------------------------------- |
+| **Performance regression** in context switching       | Low         | High   | Benchmark before/after; C++20 should be faster                                   |
+| **Coroutine frame lifetime bugs** (use-after-destroy) | Medium      | High   | ASAN testing, RAII wrapper for handle, code review                               |
+| **Data races on resume**                              | Medium      | High   | TSAN testing, careful await_suspend() implementation                             |
+| **LocalValue corruption** across threads              | Low         | High   | Dedicated test with 4+ concurrent coroutines                                     |
+| **Shutdown race conditions**                          | Medium      | Medium | Replicate existing mutex/cv pattern in new design                                |
+| **Missed coroutine consumer** during migration        | Low         | Medium | Exhaustive grep audit ([Section 5.4](#54-all-coroutine-touchpoints) is complete) |
+| **Compiler bugs** in coroutine codegen                | Low         | Medium | Test on all three compilers (GCC, Clang, MSVC)                                   |
+| **Exception loss** across suspension points           | Medium      | Medium | Test exception propagation in every phase                                        |
+| **Third-party code depending on Boost.Coroutine**     | Very Low    | Low    | Grep confirms only internal usage                                                |
+| **Dangling references in coroutine frames**           | Medium      | High   | ASAN testing, avoid reference params in coroutine functions, use shared_ptr      |
+| **Colored function infection spreading**              | Low         | Medium | Only 4 call sites need co_await; no nested handlers suspend                      |
+| **Symmetric transfer not available**                  | Very Low    | High   | All target compilers (GCC 12+, Clang 16+) support symmetric transfer             |
+| **Future handler adding deep yield**                  | Low         | Medium | Code review + CI: static analysis flag any yield from nested depth               |
 
 ### 9.2 Rollback Strategy
 
@@ -1101,7 +1104,7 @@ graph TD
     P4 --> PREVENT
 ```
 
-**Key principle**: Old `Coro` class and `postCoro()` remain in the codebase through Phases 1-3. They are only removed in Phase 4, after all migration is validated. Each phase is independently revertible via `git revert`.
+**Key principle**: Old `Coro` class and `postCoro()` remain in the codebase through Phases 1-3. They are only removed in [Phase 4](#phase-4-cleanup), after all migration is validated. Each phase is independently revertible via `git revert`.
 
 ### 9.3 Specific Risk: Stackful → Stackless Limitation
 
@@ -1496,7 +1499,7 @@ ASAN annotations (`__sanitizer_start_switch_fiber` / `__sanitizer_finish_switch_
 The migration only removes `Boost::coroutine`. rippled's production server code (`BaseHTTPPeer.h`) and test infrastructure (`yield_to.h`) still use `boost::asio::spawn`, which depends on `Boost.Context` for stackful fiber execution. Migrating those call sites to `boost::asio::co_spawn` / `boost::asio::awaitable` is a separate initiative. See [Concern 6](#concern-6-yield_toh--boostasiospawn) for details.
 
 **Can C++20 stackless coroutines yield from deeply nested function calls?**
-No — `co_await` can only appear in the immediate coroutine function body. However, an exhaustive audit confirmed that all `yield()` calls in rippled are at the top level of their lambda or handler function. No deep nesting exists. See Section 4.6, Concern 1.
+No — `co_await` can only appear in the immediate coroutine function body. However, an exhaustive audit confirmed that all `yield()` calls in rippled are at the top level of their lambda or handler function. No deep nesting exists. See [Section 4.6, Concern 1](#concern-1-cannot-suspend-from-nested-call-stacks).
 
 **Why was `RipplePathFind` not migrated to use `co_await` as the plan originally proposed?**
 During implementation, it was simpler and more robust to replace the coroutine-based yield/post pattern with a `std::condition_variable` synchronous wait. Since `RipplePathFind` is the only handler that suspends, and it already runs on a JobQueue worker thread, blocking that thread for up to 30 seconds is acceptable. This eliminates coroutine complexity from the handler entirely.