fix(api): gate playout mutations on EntityLocker build lock (409) + mirror lock state in SPA (fixes #215)

Blazor disabled per-playout Reset/Erase/Delete/Edit while a BuildPlayout was
in flight (EntityLocker.IsPlayoutLocked); the REST API had no equivalent, so a
client could race an in-flight build with a destructive ExecuteDelete and leave
a half-built playout. After Blazor removal this safety invariant would vanish
entirely (adversarial-reviewer#18 removal gate).

Server:
- Add public ApiResults.ConflictProblem(title, detail) (409, mirrors NotFoundProblem).
- Inject IEntityLocker into PlayoutController; guard every id-keyed mutation
  (PUT {id}, PUT .../deco, PUT .../alternate-schedules, PUT .../templates,
  POST .../erase-items, POST .../erase-items-and-history, DELETE {id}) → 409
  when IsPlayoutLocked(id); add [ProducesResponseType(...409)] to each.
- Guard ChannelController.ResetPlayout the same way after resolving the id.
- reset-all stays 202 (ResetAllPlayoutsHandler already skips locked playouts).
- Stamp IsLocked onto PlayoutListItemResponseModel from IsPlayoutLocked.

SPA:
- Disable Reset/Erase/Erase-and-history/Delete for a locked row + show a
  "Building…" Badge; on a 409 surface the error and refresh the list.

Tests: controller-level 409 guard tests (delete/erase/PUT/deco/channel-reset)
+ IsLocked projection test; new OpenAPI contract + metadata 409 rows.
Docs: api-conventions §3a, blazor-route-parity playouts verdict, decisions.md.
Regenerated v1.json + web types.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

ErsatzTV/Controllers/Api/ChannelController.cs

@@ -7,6 +7,7 @@ using ErsatzTV.Controllers.Api.Requests;
 using ErsatzTV.Core;
 using ErsatzTV.Core.Api.Channels;
 using ErsatzTV.Core.Domain;
+using ErsatzTV.Core.Interfaces.Locking;
 using ErsatzTV.Core.Scheduling;
 using ErsatzTV.Extensions;
 using MediatR;
@@ -16,7 +17,10 @@ using Microsoft.AspNetCore.Mvc;
 namespace ErsatzTV.Controllers.Api;
 
 [ApiController]
-public class ChannelController(ChannelWriter<IBackgroundServiceRequest> workerChannel, IMediator mediator)
+public class ChannelController(
+    ChannelWriter<IBackgroundServiceRequest> workerChannel,
+    IMediator mediator,
+    IEntityLocker entityLocker)
 {
     [HttpGet("/api/channels")]
     [EndpointGroupName("general")]
@@ -192,6 +196,7 @@ public class ChannelController(ChannelWriter<IBackgroundServiceRequest> workerCh
     [EndpointGroupName("general")]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     public async Task<IActionResult> ResetPlayout(
         string channelNumber,
         [FromQuery] PlayoutBuildMode? mode,
@@ -201,6 +206,14 @@ public class ChannelController(ChannelWriter<IBackgroundServiceRequest> workerCh
             await mediator.Send(new GetPlayoutIdByChannelNumber(channelNumber), cancellationToken);
         foreach (int playoutId in maybePlayoutId)
         {
+            // Mirror Blazor's EntityLocker gating: don't enqueue a rebuild while one is already in flight.
+            if (entityLocker.IsPlayoutLocked(playoutId))
+            {
+                return ApiResults.ConflictProblem(
+                    "Playout build in progress",
+                    "A build for this playout is currently in progress; try again once it completes.");
+            }
+
             PlayoutBuildMode buildMode = mode ?? await DefaultResetMode(playoutId, cancellationToken);
             await workerChannel.WriteAsync(new BuildPlayout(playoutId, buildMode), cancellationToken);
             return new OkResult();

ErsatzTV/Controllers/Api/PlayoutController.cs

@@ -10,6 +10,7 @@ using ErsatzTV.Core.Api.Playouts;
 using ErsatzTV.Core.Api.Scheduling;
 using ErsatzTV.Core.Domain;
 using ErsatzTV.Core.Domain.Filler;
+using ErsatzTV.Core.Interfaces.Locking;
 using ErsatzTV.Extensions;
 using MediatR;
 using Microsoft.AspNetCore.Http;
@@ -18,10 +19,21 @@ using Microsoft.AspNetCore.Mvc;
 namespace ErsatzTV.Controllers.Api;
 
 [ApiController]
-public class PlayoutController(IMediator mediator) : ControllerBase
+public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) : ControllerBase
 {
     private const int MaxPageSize = 100;
 
+    // Blazor disables per-playout Reset/Erase/Delete/Edit while a build is in flight
+    // (EntityLocker.IsPlayoutLocked); the API mirrors that invariant by rejecting any
+    // id-keyed mutation with 409 while the build lock is held. See docs/decisions.md 2026-07-10.
+    private const string BuildInProgressTitle = "Playout build in progress";
+
+    private const string BuildInProgressDetail =
+        "A build for this playout is currently in progress; try again once it completes.";
+
+    private static IActionResult PlayoutLockedProblem() =>
+        ApiResults.ConflictProblem(BuildInProgressTitle, BuildInProgressDetail);
+
     [HttpGet("/api/playouts", Name = "GetPlayouts")]
     [Tags("Playouts")]
     [EndpointSummary("List playouts")]
@@ -37,7 +49,7 @@ public class PlayoutController(IMediator mediator) : ControllerBase
             await mediator.Send(new GetPagedPlayouts(query, pageNum, pageSize), cancellationToken);
         return new PagedPlayoutsResponseModel(
             result.TotalCount,
-            result.Page.Map(ToListItemResponse).ToList());
+            result.Page.Map(vm => ToListItemResponse(vm, entityLocker.IsPlayoutLocked(vm.PlayoutId))).ToList());
     }
 
     [HttpGet("/api/playouts/warnings/count", Name = "GetPlayoutWarningsCount")]
@@ -131,12 +143,18 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(PlayoutResponseModel), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> Update(
         int id,
         [Required] [FromBody] UpdatePlayoutDetailsRequest request,
         CancellationToken cancellationToken)
     {
+        if (entityLocker.IsPlayoutLocked(id))
+        {
+            return PlayoutLockedProblem();
+        }
+
         Option<PlayoutNameViewModel> maybePlayout = await mediator.Send(new GetPlayoutById(id), cancellationToken);
         if (maybePlayout.IsNone)
         {
@@ -204,12 +222,18 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(PlayoutResponseModel), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> UpdateDefaultDeco(
         int id,
         [Required] [FromBody] UpdateDefaultDecoRequest request,
         CancellationToken cancellationToken)
     {
+        if (entityLocker.IsPlayoutLocked(id))
+        {
+            return PlayoutLockedProblem();
+        }
+
         Option<PlayoutNameViewModel> maybePlayout = await mediator.Send(new GetPlayoutById(id), cancellationToken);
         if (maybePlayout.IsNone)
         {
@@ -284,12 +308,18 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(List<PlayoutAlternateScheduleResponseModel>), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> ReplaceAlternateSchedules(
         int id,
         [Required] [FromBody] ReplacePlayoutAlternateSchedulesRequest request,
         CancellationToken cancellationToken)
     {
+        if (entityLocker.IsPlayoutLocked(id))
+        {
+            return PlayoutLockedProblem();
+        }
+
         Option<PlayoutNameViewModel> maybePlayout = await mediator.Send(new GetPlayoutById(id), cancellationToken);
         if (maybePlayout.IsNone)
         {
@@ -376,12 +406,18 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(List<PlayoutTemplateResponseModel>), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> ReplaceTemplates(
         int id,
         [Required] [FromBody] ReplacePlayoutTemplatesRequest request,
         CancellationToken cancellationToken)
     {
+        if (entityLocker.IsPlayoutLocked(id))
+        {
+            return PlayoutLockedProblem();
+        }
+
         Option<PlayoutNameViewModel> maybePlayout = await mediator.Send(new GetPlayoutById(id), cancellationToken);
         if (maybePlayout.IsNone)
         {
@@ -515,6 +551,9 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointSummary("Reset all playouts")]
     [EndpointGroupName("general")]
     [ProducesResponseType(StatusCodes.Status202Accepted)]
+    // No 409 lock guard here (unlike the id-keyed mutations): ResetAllPlayoutsHandler already
+    // skips any playout whose build lock is held, matching Blazor. It is a fire-and-forget
+    // bulk enqueue, so it always accepts. See docs/decisions.md 2026-07-10.
     public async Task<IActionResult> ResetAll(CancellationToken cancellationToken)
     {
         await mediator.Send(new ResetAllPlayouts(), cancellationToken);
@@ -531,9 +570,15 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointGroupName("general")]
     [ProducesResponseType(StatusCodes.Status204NoContent)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> EraseItems(int id, CancellationToken cancellationToken)
     {
+        if (entityLocker.IsPlayoutLocked(id))
+        {
+            return PlayoutLockedProblem();
+        }
+
         Option<PlayoutNameViewModel> maybePlayout = await mediator.Send(new GetPlayoutById(id), cancellationToken);
         if (maybePlayout.IsNone)
         {
@@ -563,9 +608,15 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointGroupName("general")]
     [ProducesResponseType(StatusCodes.Status204NoContent)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> EraseItemsAndHistory(int id, CancellationToken cancellationToken)
     {
+        if (entityLocker.IsPlayoutLocked(id))
+        {
+            return PlayoutLockedProblem();
+        }
+
         Option<PlayoutNameViewModel> maybePlayout = await mediator.Send(new GetPlayoutById(id), cancellationToken);
         if (maybePlayout.IsNone)
         {
@@ -608,9 +659,15 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointGroupName("general")]
     [ProducesResponseType(StatusCodes.Status204NoContent)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> Delete(int id, CancellationToken cancellationToken)
     {
+        if (entityLocker.IsPlayoutLocked(id))
+        {
+            return PlayoutLockedProblem();
+        }
+
         Either<BaseError, Unit> result = await mediator.Send(new DeletePlayout(id), cancellationToken);
         return result.ToDeletedResult();
     }
@@ -722,7 +779,7 @@ public class PlayoutController(IMediator mediator) : ControllerBase
             vm.EndDay,
             vm.EndYear);
 
-    private static PlayoutListItemResponseModel ToListItemResponse(PlayoutNameViewModel vm) =>
+    private static PlayoutListItemResponseModel ToListItemResponse(PlayoutNameViewModel vm, bool isLocked) =>
         new(
             vm.PlayoutId,
             vm.ChannelNumber,
@@ -731,7 +788,8 @@ public class PlayoutController(IMediator mediator) : ControllerBase
             vm.ScheduleName,
             vm.DbDailyRebuildTime,
             ToBuildStatus(vm.BuildStatus),
-            vm.PlayoutMode);
+            vm.PlayoutMode,
+            isLocked);
 
     private static PlayoutBuildStatusResponseModel ToBuildStatus(PlayoutBuildStatus buildStatus) =>
         buildStatus is null