update state

Author: adrianlyjak

src/workflows/runtime/state.py

@@ -13,20 +13,41 @@
 
 @dataclass
 class WorkflowBrokerState:
-    """Asyncio-native broker state holder managed by the runtime.
+    """Asyncio-native, serializable broker state for a single workflow run.
 
-    Note: The state store remains owned by `Context` and is not included here.
+    Owned and mutated by ``WorkflowBroker``; excludes the user state store
+    (owned by ``Context``). See ``SerializedContext`` for the wire format.
     """
 
+    # True while a run is active; cleared on completion/timeout/cancel
     is_running: bool = False
+
+    # Event stream for observers; broker writes lifecycle/system events here
+    # A None item may be used as a sentinel for end-of-stream
     streaming_queue: asyncio.Queue[Event | None] = field(
         default_factory=lambda: asyncio.Queue()
     )
+
+    # Per-step and waiter inbound queues: step name / waiter ID -> asyncio.Queue
+    # Workers consume from these to drive step execution
     queues: dict[str, asyncio.Queue[Event]] = field(default_factory=dict)
+
+    # Buffers used by collect_events: buffer_id -> fully.qualified.Event -> [Event]
+    # Enables waiting for specific combinations of events
     event_buffers: dict[str, dict[str, list[Event]]] = field(default_factory=dict)
+
+    # Step name -> list of input events currently being processed by that step
+    # Also used to seed queues on deserialization so in-flight work can resume
     in_progress: dict[str, list[Event]] = field(default_factory=dict)
+
+    # (step_name, input_event_class_name) recorded when a step outputs an event
+    # Consumed by drawing/visualization utilities to reconstruct edges
     accepted_events: list[tuple[str, str]] = field(default_factory=list)
+
+    # Append-only log of all events dispatched by the broker in order
     broker_log: list[Event] = field(default_factory=list)
+
+    # Active waiter IDs to suppress duplicate waiter events (e.g., UI prompts)
     waiting_ids: set[str] = field(default_factory=set)
 
     def to_serialized(self, serializer: BaseSerializer) -> SerializedContext: