Document async-stream as canonical Response::Stream helper

docs/asynchronous-outbound-messaging-design.md

@@ -39,13 +39,13 @@ sections describe how to build that actor from first principles using the biased
 
 The implementation must satisfy the following core requirements:
 
-| ID | Requirement |
+| ID  | Requirement                                                                                                                                            |
 | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| G1 | Any async task must be able to push frames to a live connection. |
-| G2 | Ordering-safety: Pushed frames must interleave correctly with normal request/response traffic and respect any per-message sequencing rules. |
-| G3 | Back-pressure: Writers must block (or fail fast) when the peer cannot drain the socket, preventing unbounded memory consumption. |
-| G4 | Generic—independent of any particular protocol; usable by both servers and clients built on wireframe. |
-| G5 | Preserve the simple “return a reply” path for code that does not need pushes, ensuring backward compatibility and low friction for existing users. |
+| G1  | Any async task must be able to push frames to a live connection.                                                                                       |
+| G2  | Ordering-safety: Pushed frames must interleave correctly with normal request/response traffic and respect any per-message sequencing rules.            |
+| G3  | Back-pressure: Writers must block (or fail fast) when the peer cannot drain the socket, preventing unbounded memory consumption.                       |
+| G4  | Generic—independent of any particular protocol; usable by both servers and clients built on wireframe.                                                 |
+| G5  | Preserve the simple “return a reply” path for code that does not need pushes, ensuring backward compatibility and low friction for existing users.     |
 
 ## 3. Core Architecture: The Connection Actor
 
@@ -70,7 +70,7 @@ manage two distinct, bounded `tokio::mpsc` channels for pushed frames:
    messages like heartbeats, session control notifications, or protocol-level
    pings.
 
-1. `low_priority_push_rx: mpsc::Receiver<F>`: For standard, non-urgent
+2. `low_priority_push_rx: mpsc::Receiver<F>`: For standard, non-urgent
    background messages like log forwarding or secondary status updates.
 
 The bounded nature of these channels provides an inherent and robust
@@ -90,13 +90,13 @@ The polling order will be:
 1. **Graceful Shutdown Signal:** The `CancellationToken` will be checked first
    to ensure immediate reaction to a server-wide shutdown request.
 
-1. **High-Priority Push Channel:** Messages from `high_priority_push_rx` will be
+2. **High-Priority Push Channel:** Messages from `high_priority_push_rx` will be
    drained next.
 
-1. **Low-Priority Push Channel:** Messages from `low_priority_push_rx` will be
+3. **Low-Priority Push Channel:** Messages from `low_priority_push_rx` will be
    processed after all high-priority messages.
 
-1. **Handler Response Stream:** Frames from the active request's
+4. **Handler Response Stream:** Frames from the active request's
    `Response::Stream` will be processed last.
 
 ```rust
@@ -684,11 +684,11 @@ sequenceDiagram
 
 ## 8. Measurable Objectives & Success Criteria
 
-| Category | Objective | Success Metric |
+| Category        | Objective                                                                                                           | Success Metric                                                                                                                                                                              |
 | --------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| API Correctness | The PushHandle, SessionRegistry, and WireframeProtocol trait are implemented exactly as specified in this document. | 100% of the public API surface is present and correctly typed. |
-| Functionality | Pushed frames are delivered reliably and in the correct order of priority. | A test with concurrent high-priority, low-priority, and streaming producers must show that all frames are delivered and that the final written sequence respects the strict priority order. |
-| Back-pressure | A slow consumer must cause producer tasks to suspend without consuming unbounded memory. | A test with a slow consumer and a fast producer must show the producer's push().await call blocks, and the process memory usage remains stable. |
-| Resilience | The SessionRegistry must not leak memory when connections are terminated. | A long-running test that creates and destroys thousands of connections must show no corresponding growth in the SessionRegistry's size or the process's overall memory footprint. |
-| Performance | The overhead of the push mechanism should be minimal for connections that do not use it. | A benchmark of a simple request-response workload with the push feature enabled (but unused) should show < 2% performance degradation compared to a build without the feature. |
-| Performance | The latency for a high-priority push under no contention should be negligible. | The time from push_high_priority().await returning to the frame being written to the socket buffer should be < 10µs. |
+| API Correctness | The PushHandle, SessionRegistry, and WireframeProtocol trait are implemented exactly as specified in this document. | 100% of the public API surface is present and correctly typed.                                                                                                                              |
+| Functionality   | Pushed frames are delivered reliably and in the correct order of priority.                                          | A test with concurrent high-priority, low-priority, and streaming producers must show that all frames are delivered and that the final written sequence respects the strict priority order. |
+| Back-pressure   | A slow consumer must cause producer tasks to suspend without consuming unbounded memory.                            | A test with a slow consumer and a fast producer must show the producer's push().await call blocks, and the process memory usage remains stable.                                             |
+| Resilience      | The SessionRegistry must not leak memory when connections are terminated.                                           | A long-running test that creates and destroys thousands of connections must show no corresponding growth in the SessionRegistry's size or the process's overall memory footprint.           |
+| Performance     | The overhead of the push mechanism should be minimal for connections that do not use it.                            | A benchmark of a simple request-response workload with the push feature enabled (but unused) should show < 2% performance degradation compared to a build without the feature.              |
+| Performance     | The latency for a high-priority push under no contention should be negligible.                                      | The time from push_high_priority().await returning to the frame being written to the socket buffer should be < 10µs.                                                                        |

docs/asynchronous-outbound-messaging-roadmap.md

@@ -29,8 +29,10 @@ design documents.
 - [x] **Leak-proof `SessionRegistry`** using `dashmap::DashMap` and `Weak`
   pointers ([Design §4.2][design-registry],
   [Resilience Guide §3.2][resilience-registry]).
-- [ ] **Document `async-stream`** for creating `Response::Stream` values
+- [x] **Document `async-stream`** for creating `Response::Stream` values
   ([Roadmap #2.4][roadmap-2-4]).
+- [ ] **Example handler using `async-stream`** demonstrating `Response::Stream`
+  generation in the examples directory.
 - [ ] **Tests covering streams and push delivery** drawing on
   [Testing Guide §4][testing-guide-advanced].
 

docs/multi-packet-and-streaming-responses-design.md

@@ -38,11 +38,10 @@ The implementation must satisfy the following core requirements:
 ## 3. Core Architecture: Declarative Streaming
 
 The cornerstone of this design is a move to a purely **declarative streaming
-model**. Instead of providing handlers with an imperative `FrameSink` to push
-frames into, handlers will declaratively return a description of the entire
-response. This approach significantly simplifies the API surface, improves
-testability, and eliminates a class of resource management issues associated
-with sink-based designs.
+model**. Handlers declaratively return a description of the entire response.
+This approach significantly simplifies the API surface, improves testability,
+and eliminates a class of resource management issues associated with sink-based
+designs.
 
 ### 3.1 The Connection Actor's Role
 
@@ -61,12 +60,12 @@ explicit channel management.
 ### 3.2 The `async-stream` Crate
 
 To provide an ergonomic way for developers to generate streams using
-imperative-style logic (e.g., inside a `for` loop), `wireframe` will adopt and
-recommend the `async-stream` crate. This crate provides macros (`stream!` and
+imperative-style logic (e.g., inside a `for` loop), `wireframe` adopts and
+recommends the `async-stream` crate. This crate provides macros (`stream!` and
 `try_stream!`) that transform imperative `yield` statements into a fully
-compliant `Stream` object. This gives developers the best of both worlds: the
-intuitive feel of imperative code generation without the API complexity of a
-separate `FrameSink` type.
+compliant `Stream` object. This gives developers the intuitive feel of
+imperative code generation with minimal API complexity. The library recommends
+this pattern as the canonical way to build `Response::Stream` values.
 
 ## 4. Public API Surface
 
@@ -252,7 +251,7 @@ hang.
 | Category        | Objective                                                                                                                                        | Success Metric                                                                                                                                             |
 | API Correctness | The Response enum and FrameStream type alias are implemented exactly as specified in this document.                                              | 100% of the public API surface is present and correctly typed.                                                                                             |
 | Functionality   | A handler returning a stream of N frames results in N frames being written to the socket in the correct order.                                   | A test suite confirms 100% frame delivery and strict ordering for Response::Vec and Response::Stream.                                                      |
-| Ergonomics      | The async-stream pattern is documented as the canonical approach for dynamic stream generation and is demonstrably simpler than a FrameSink API. | The official examples and documentation exclusively use the declarative Response model.                                                                    |
+| Ergonomics      | The async-stream pattern is documented as the canonical approach for dynamic stream generation.                                                  | The official examples and documentation exclusively use the declarative Response model.                                                                    |
 | Performance     | The Response::Vec variant has measurably lower allocation and dispatch overhead than Response::Stream for small, fixed-size responses.           | A criterion benchmark confirms that Response::Vec is at least 50% faster and performs fewer allocations than Response::Stream for a response of 10 frames. |
 | Error Handling  | A WireframeError::Protocol error yielded from a stream correctly triggers the handle_error protocol callback without terminating the connection. | An integration test confirms that a protocol-level error is correctly formatted and sent to the client, while the connection remains open.                 |
 

docs/the-road-to-wireframe-1-0-feature-set-philosophy-and-capability-maturity.md

@@ -40,10 +40,9 @@ server-initiated pushes and streaming responses.
 
 #### The Unified `Response` Enum and Declarative Handler Model
 
-To provide a clean, unified API, the handler return type will evolve. The
-imperative `FrameSink` model, which required a separate handler signature and
-introduced resource management complexities, will be replaced by a more
-ergonomic, declarative approach. 1 Handlers will return an enhanced
+To provide a clean, unified API, the handler return type will evolve. A more
+ergonomic, declarative approach replaces the previous imperative model.
+Handlers will return an enhanced
 
 `Response` enum, giving developers clear and efficient ways to express their
 intent.
@@ -64,11 +63,11 @@ pub enum Response<F = Frame, E = MyProtocolError> {
 ```
 
 This design is powered by the `async-stream` crate, which allows developers to
-write imperative-looking logic that generates a declarative `Stream` object.
-This provides the best of both worlds: the intuitive feel of a
-
-`for` loop for generating frames, without the API complexity of a separate
-`Sink` type.
+write imperative-looking logic that generates a declarative `Stream` object. It
+provides the best of both worlds: the intuitive feel of a `for` loop for
+generating frames with minimal API complexity. The project recommends
+`async-stream` as the canonical method for constructing `Response::Stream`
+values.
 
 Rust