S12 - Async feedback for scheduling

README.md

@@ -83,7 +83,8 @@ the solver live in `model.scheduling`. Each group requirement combines its group
 ID and appearance count in one record.
 
 `service.port.SchedulingEngine` is the application-owned interface for solving a
-scheduling problem. `SchedulingService` calls this interface; dependency injection
+scheduling problem. `SchedulingRuns` calls this interface for background runs;
+`SchedulingService` retains the synchronous service entry point. Dependency injection
 supplies `solver.OrToolsSchedulingEngine`. The port accepts and returns domain
 types, so neither the caller nor the contract depends on OR-Tools or the concrete
 school-management service. Architecture tests enforce the port's location and
@@ -160,11 +161,22 @@ dayparts; preschool groups once; showcases every daypart. See
 [show-scheduling-rules.md](show-scheduling-rules.md) for the full hard constraints,
 coach exceptions, ordering and optimization rules.
 
-`POST /api/dance-schools/{schoolId}/shows/{showId}/schedule` generates an ordered
-draft using OR-Tools with a total thirty-minute time limit. A feasible result is
-accepted without claiming optimality. Concurrent runs and stale results return
-`409`; failures retain existing assignments. Development and production proxies
-allow 31 minutes.
+`POST /api/dance-schools/{schoolId}/shows/{showId}/schedule` returns `202` with a
+run identifier and starts an ordered draft calculation in the background using
+OR-Tools with a total thirty-minute time limit. Duplicate starts for the same
+show return `409`; different shows may run concurrently. A feasible result is
+accepted without claiming optimality. Stale results and failures retain existing
+assignments and appear as distinct terminal run states.
+
+`GET .../shows/{showId}/schedule` returns the latest run (`204` if none exists).
+`GET /api/scheduling/events` streams SSE JSON objects containing a `runs` snapshot
+on connection and changes, or `runs: null` as a fifteen-second heartbeat. Clients
+recover current state on reconnection rather than requiring event replay. The
+production proxy disables buffering. The UI shows phase, elapsed time, solution
+discovery and final objective scores, and reports completion in an application-wide
+snackbar. Reloading recovers the latest state without replaying old notifications.
+Run state currently shares the application's in-memory lifetime; durable restart
+recovery requires the PostgreSQL integration specified in S16.
 
 `PUT .../shows/{showId}/assignments` accepts `{"assignments":[[1,2],[3]]}`, an
 ordered list of group IDs per daypart. Incomplete or invalid drafts can be saved;