From 62155c3fdc22c27bb27db3ba27c2e5ff8dc7674c Mon Sep 17 00:00:00 2001
From: Leynos <leynos@troubledskies.net>
Date: Thu, 26 Jun 2025 00:16:13 +0100
Subject: [PATCH 1/2] Document actor state consolidation

---
 .../asynchronous-outbound-messaging-design.md | 26 +++++++++++++++++++
 ...asynchronous-outbound-messaging-roadmap.md |  3 +++
 2 files changed, 29 insertions(+)

diff --git a/docs/asynchronous-outbound-messaging-design.md b/docs/asynchronous-outbound-messaging-design.md
index 2e558797..8874b912 100644
--- a/docs/asynchronous-outbound-messaging-design.md
+++ b/docs/asynchronous-outbound-messaging-design.md
@@ -178,6 +178,32 @@ sequenceDiagram
     Note over Outbox: Holds frames while the socket is busy.
 ```
 
+### 3.4 Actor state management
+
+The connection actor polls four sources: a shutdown token, high and low priority
+push channels, and an optional response stream. Earlier drafts tracked a boolean
+for each source, leading to verbose state updates. The actor now stores each
+receiver as an `Option` and counts how many sources have closed.
+
+```rust
+enum RunState {
+    Active,
+    ShuttingDown,
+    Finished,
+}
+
+struct ActorState {
+    run_state: RunState,
+    closed_sources: u8,
+    total_sources: u8,
+}
+```
+
+`total_sources` is calculated when the actor starts. Whenever a receiver returns
+`None` it is set to `None` and `closed_sources` increments. When
+`closed_sources == total_sources` the loop exits. This consolidation clarifies
+progress through the actor lifecycle and reduces manual flag management.
+
 ## 4. Public API Surface
 
 The public API is designed for ergonomics, safety, and extensibility.
diff --git a/docs/asynchronous-outbound-messaging-roadmap.md b/docs/asynchronous-outbound-messaging-roadmap.md
index 6cb4ece0..50a58b5f 100644
--- a/docs/asynchronous-outbound-messaging-roadmap.md
+++ b/docs/asynchronous-outbound-messaging-roadmap.md
@@ -13,6 +13,8 @@ design documents.
 - [x] **Connection actor** with a biased `select!` loop that polls for shutdown,
   high/low queues and response streams as described in
   [Design §3.2][design-write-loop].
+- [ ] **Run state consolidation** using `Option` receivers and a closed source
+  counter ([Design §3.4][design-actor-state]).
 - [ ] **Internal protocol hooks** `before_send` and `on_command_end` invoked
   from the actor ([Design §4.3][design-hooks]).
 
@@ -52,6 +54,7 @@ design documents.
 - [ ] **User guides and examples** demonstrating server-initiated messaging
   ([Design §7][design-use-cases]).
 
+[design-actor-state]: asynchronous-outbound-messaging-design.md#34-actor-state-management
 [design-dlq]: asynchronous-outbound-messaging-design.md#52-optional-dead-letter-queue-dlq-for-critical-messages
 [design-errors]: asynchronous-outbound-messaging-design.md#5-error-handling--resilience
 [design-hooks]: asynchronous-outbound-messaging-design.md#43-configuration-via-the-wireframeprotocol-trait

From 23abd59bd46e1ef6f9418a3e9a23055485e52f8b Mon Sep 17 00:00:00 2001
From: Leynos <leynos@troubledskies.net>
Date: Thu, 26 Jun 2025 19:21:16 +0100
Subject: [PATCH 2/2] Refine actor state section

---
 docs/asynchronous-outbound-messaging-design.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/asynchronous-outbound-messaging-design.md b/docs/asynchronous-outbound-messaging-design.md
index 8874b912..652a632a 100644
--- a/docs/asynchronous-outbound-messaging-design.md
+++ b/docs/asynchronous-outbound-messaging-design.md
@@ -180,10 +180,10 @@ sequenceDiagram
 
 ### 3.4 Actor state management
 
-The connection actor polls four sources: a shutdown token, high and low priority
-push channels, and an optional response stream. Earlier drafts tracked a boolean
-for each source, leading to verbose state updates. The actor now stores each
-receiver as an `Option` and counts how many sources have closed.
+The connection actor polls four sources: a shutdown token, high- and
+low-priority push channels, and an optional response stream. Earlier drafts
+tracked a boolean for each source, leading to verbose state updates. The actor
+now stores each receiver as an `Option` and counts how many sources have closed.
 
 ```rust
 enum RunState {
@@ -194,13 +194,13 @@ enum RunState {
 
 struct ActorState {
     run_state: RunState,
-    closed_sources: u8,
-    total_sources: u8,
+    closed_sources: usize,
+    total_sources: usize,
 }
 ```
 
 `total_sources` is calculated when the actor starts. Whenever a receiver returns
-`None` it is set to `None` and `closed_sources` increments. When
+`None`, it is set to `None` and `closed_sources` increments. When
 `closed_sources == total_sources` the loop exits. This consolidation clarifies
 progress through the actor lifecycle and reduces manual flag management.