# Event Fan-Out (SSE/Streaming)

## Module
Orchestrator

## Status
IMPLEMENTED

## Description
Job and pack-run streaming coordinators with stream payload models for real-time SSE event delivery.

## Implementation Details
- **Modules**: `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Streaming/`, `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/Events/`
- **Key Classes**:
  - `JobStreamCoordinator` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Streaming/JobStreamCoordinator.cs`) - coordinates SSE streaming for job lifecycle events to connected clients
  - `PackRunStreamCoordinator` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Streaming/PackRunStreamCoordinator.cs`) - coordinates streaming for pack-run execution events
  - `RunStreamCoordinator` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Streaming/RunStreamCoordinator.cs`) - coordinates streaming for individual run events
  - `SseWriter` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Streaming/SseWriter.cs`) - writes Server-Sent Events to HTTP response streams
  - `StreamOptions` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Streaming/StreamOptions.cs`) - configuration for stream connections (heartbeat interval, buffer size, timeout)
  - `StreamPayloads` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Streaming/StreamPayloads.cs`) - typed payload models for stream events (job progress, pack-run status, log lines)
  - `StreamEndpoints` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/StreamEndpoints.cs`) - REST endpoints for SSE stream subscription
  - `EventEnvelope` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/Events/EventEnvelope.cs`) - typed event envelope wrapping domain events for streaming
  - `OrchestratorEventPublisher` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Infrastructure/Events/OrchestratorEventPublisher.cs`) - concrete event publisher routing events to stream coordinators
- **Interfaces**: `IEventPublisher` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/Events/IEventPublisher.cs`)
- **Source**: Feature matrix scan

## E2E Test Plan
- [ ] Subscribe to the job stream via `StreamEndpoints` and trigger a job; verify SSE events are received for each state transition
- [ ] Subscribe to the pack-run stream via `PackRunStreamCoordinator` and execute a pack; verify progress events include step index, status, and log lines
- [ ] Verify heartbeat: subscribe to a stream and wait without events; confirm heartbeat events arrive at the `StreamOptions` configured interval
- [ ] Subscribe with two clients to the same job stream and verify both receive identical events (fan-out via `JobStreamCoordinator`)
- [ ] Disconnect a client mid-stream and verify the stream coordinator cleans up the connection without affecting other subscribers
- [ ] Trigger a rapid sequence of events and verify `SseWriter` delivers them in order without drops
- [ ] Verify stream payloads: each event contains a typed payload matching the `StreamPayloads` model
- [ ] Test stream timeout: idle for longer than `StreamOptions.Timeout` and verify the connection closes gracefully