Merge remote-tracking branch 'origin/main' into feat/253-pr3-diff-scalar

# Conflicts:
#	docs/decisions.md

ErsatzTV/Controllers/Api/ChannelController.cs

@@ -211,7 +211,7 @@ public class ChannelController(
         "progress) and all other playout kinds use Reset (rebuild from scratch), matching the Blazor UI. " +
         "Pass mode to force a specific PlayoutBuildMode.")]
     [EndpointGroupName("general")]
-    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status202Accepted)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     public async Task<IActionResult> ResetPlayout(
@@ -233,7 +233,7 @@ public class ChannelController(
 
             PlayoutBuildMode buildMode = mode ?? await DefaultResetMode(playoutId, cancellationToken);
             await workerChannel.WriteAsync(new BuildPlayout(playoutId, buildMode), cancellationToken);
-            return new OkResult();
+            return new AcceptedResult();
         }
 
         return ApiResults.NotFoundProblem();

ErsatzTV/Controllers/Api/DecoTemplateController.cs

@@ -143,6 +143,9 @@ public class DecoTemplateController(IMediator mediator) : ControllerBase
     [HttpGet("/api/deco-templates/{id:int}/items")]
     [Tags("DecoTemplates")]
     [EndpointSummary("Get deco template items")]
+    [EndpointDescription(
+        "Returns the deco template's items and a strong ETag of the deco template's version. Pass that ETag " +
+        "back as If-Match on the replace (PUT) to detect a concurrent edit (issue #253).")]
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(List<DecoTemplateItemResponseModel>), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
@@ -154,6 +157,9 @@ public class DecoTemplateController(IMediator mediator) : ControllerBase
             return ApiResults.NotFoundProblem();
         }
 
+        // The items GET returns children, not the root, so read the deco template's version for the ETag.
+        ConcurrencyHeaders.SetETag(Response, decoTemplate.Map(t => t.Version).IfNone(0));
+
         List<DecoTemplateItemViewModel> items = await mediator.Send(new GetDecoTemplateItems(id), cancellationToken);
         return new OkObjectResult(
             items.OrderBy(i => i.StartTime.TimeOfDay).Map(ProjectToResponseModel).ToList());
@@ -164,16 +170,32 @@ public class DecoTemplateController(IMediator mediator) : ControllerBase
     [EndpointSummary("Replace a deco template and its items")]
     [EndpointDescription(
         "Replaces the deco template's name and its full item list. Each item assigns a deco to a start/end time " +
-        "of day; an end time of 00:00:00 means the item runs to the end of the day. Items must not overlap.")]
+        "of day; an end time of 00:00:00 means the item runs to the end of the day. Items must not overlap. " +
+        "Send the ETag from the items GET as If-Match to reject a stale overwrite with 412 (issue #253); " +
+        "a successful response carries the new ETag.")]
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(DecoTemplateWithItemsResponseModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status412PreconditionFailed)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> Replace(
         int id,
         [Required] [FromBody] ReplaceDecoTemplateRequest request,
         CancellationToken cancellationToken)
     {
+        IfMatchCondition ifMatch = ConcurrencyHeaders.ParseIfMatch(Request);
+        if (ifMatch.Kind is IfMatchKind.Malformed)
+        {
+            return new BadRequestObjectResult(
+                new ProblemDetails
+                {
+                    Status = StatusCodes.Status400BadRequest,
+                    Title = "Invalid If-Match header",
+                    Detail = "If-Match must be a strong ETag of the resource version (e.g. \"3\") or \"*\"."
+                });
+        }
+
         Option<DecoTemplateViewModel> maybeDecoTemplate =
             await mediator.Send(new GetDecoTemplateById(id), cancellationToken);
         if (maybeDecoTemplate.IsNone)
@@ -184,18 +206,27 @@ public class DecoTemplateController(IMediator mediator) : ControllerBase
         int decoTemplateGroupId = maybeDecoTemplate.Map(t => t.DecoTemplateGroupId).IfNone(0);
 
         Either<BaseError, List<DecoTemplateItemViewModel>> result =
-            await mediator.Send(request.ToCommand(decoTemplateGroupId, id), cancellationToken);
+            await mediator.Send(
+                request.ToCommand(decoTemplateGroupId, id, ifMatch.ExpectedVersion),
+                cancellationToken);
 
         return await result.Match(
             Left: error => Task.FromResult(error.ToErrorResult()),
             Right: async _ =>
             {
+                // Reload the root (version) FIRST, then the items, so the emitted ETag is never newer than
+                // the returned items (issue #253 fail-safe ordering; matches BlockController).
                 Option<DecoTemplateViewModel> refreshed =
                     await mediator.Send(new GetDecoTemplateById(id), cancellationToken);
                 List<DecoTemplateItemViewModel> items =
                     await mediator.Send(new GetDecoTemplateItems(id), cancellationToken);
                 return refreshed.Match(
-                    Some: vm => (IActionResult)new OkObjectResult(ProjectToWithItemsResponseModel(vm, items)),
+                    Some: vm =>
+                    {
+                        // Return the new ETag so a same-tab second save doesn't 412 against its own write.
+                        ConcurrencyHeaders.SetETag(Response, vm.Version);
+                        return (IActionResult)new OkObjectResult(ProjectToWithItemsResponseModel(vm, items));
+                    },
                     None: () => ApiResults.NotFoundProblem());
             });
     }

ErsatzTV/Controllers/Api/EmbyMediaSourcesController.cs

@@ -278,6 +278,53 @@ public class EmbyMediaSourcesController(
         return new AcceptedResult();
     }
 
+    [HttpPost("/api/media-sources/emby/{id:int}/scan-collections", Name = "ScanEmbyCollections")]
+    [Tags("Emby")]
+    [EndpointSummary("Scan an Emby source's collections")]
+    [EndpointDescription(
+        "Queues a synchronization of the source's collections (fire-and-forget). Pass ?deep=true for a deep " +
+        "scan. Returns 409 while an Emby collections scan is already in progress.")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(StatusCodes.Status202Accepted)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
+    public async Task<IActionResult> ScanCollections(
+        int id,
+        [FromQuery] bool deep = false,
+        CancellationToken cancellationToken = default)
+    {
+        Option<EmbyMediaSourceViewModel> maybeSource =
+            await mediator.Send(new GetEmbyMediaSourceById(id), cancellationToken);
+        if (maybeSource.IsNone)
+        {
+            return ApiResults.NotFoundProblem();
+        }
+
+        // The collections lock IS the running scan (§3b): fail to acquire = a scan is already active → 409.
+        if (!entityLocker.LockEmbyCollections())
+        {
+            return ApiResults.ConflictProblem(
+                "Emby collections scan in progress",
+                "An Emby collections scan is already in progress; try again once it completes.");
+        }
+
+        try
+        {
+            await scannerWorkerChannel.WriteAsync(
+                new SynchronizeEmbyCollections(id, true, deep),
+                cancellationToken);
+        }
+        catch
+        {
+            // the scanner releases the lock when it processes the message; if the enqueue throws after we
+            // acquired the lock, release it here (EnqueueWithTraktLock compensating-unlock, §3b)
+            entityLocker.UnlockEmbyCollections();
+            throw;
+        }
+
+        return new AcceptedResult();
+    }
+
     // §C7: LockLibrary then enqueue the sync pair; a throw from the enqueue compensates by unlocking
     // (EnqueueWithTraktLock pattern) — a locked library is silently skipped (Blazor parity).
     private async Task EnqueueLibrarySync(int sourceId, int libraryId, CancellationToken cancellationToken)

ErsatzTV/Controllers/Api/JellyfinMediaSourcesController.cs

@@ -278,6 +278,53 @@ public class JellyfinMediaSourcesController(
         return new AcceptedResult();
     }
 
+    [HttpPost("/api/media-sources/jellyfin/{id:int}/scan-collections", Name = "ScanJellyfinCollections")]
+    [Tags("Jellyfin")]
+    [EndpointSummary("Scan a Jellyfin source's collections")]
+    [EndpointDescription(
+        "Queues a synchronization of the source's collections (fire-and-forget). Pass ?deep=true for a deep " +
+        "scan. Returns 409 while a Jellyfin collections scan is already in progress.")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(StatusCodes.Status202Accepted)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
+    public async Task<IActionResult> ScanCollections(
+        int id,
+        [FromQuery] bool deep = false,
+        CancellationToken cancellationToken = default)
+    {
+        Option<JellyfinMediaSourceViewModel> maybeSource =
+            await mediator.Send(new GetJellyfinMediaSourceById(id), cancellationToken);
+        if (maybeSource.IsNone)
+        {
+            return ApiResults.NotFoundProblem();
+        }
+
+        // The collections lock IS the running scan (§3b): fail to acquire = a scan is already active → 409.
+        if (!entityLocker.LockJellyfinCollections())
+        {
+            return ApiResults.ConflictProblem(
+                "Jellyfin collections scan in progress",
+                "A Jellyfin collections scan is already in progress; try again once it completes.");
+        }
+
+        try
+        {
+            await scannerWorkerChannel.WriteAsync(
+                new SynchronizeJellyfinCollections(id, true, deep),
+                cancellationToken);
+        }
+        catch
+        {
+            // the scanner releases the lock when it processes the message; if the enqueue throws after we
+            // acquired the lock, release it here (EnqueueWithTraktLock compensating-unlock, §3b)
+            entityLocker.UnlockJellyfinCollections();
+            throw;
+        }
+
+        return new AcceptedResult();
+    }
+
     // §C7: LockLibrary then enqueue the sync pair; a throw from the enqueue compensates by unlocking
     // (EnqueueWithTraktLock pattern) — a locked library is silently skipped (Blazor parity).
     private async Task EnqueueLibrarySync(int sourceId, int libraryId, CancellationToken cancellationToken)

ErsatzTV/Controllers/Api/LibrariesController.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using ErsatzTV.Application.Libraries;
 using ErsatzTV.Core.Api.Libraries;
 using ErsatzTV.Core.Interfaces.Repositories;
@@ -22,13 +23,18 @@ public class LibrariesController(ITelevisionRepository televisionRepository, IMe
     [HttpPost("/api/libraries/{id:int}/scan")]
     [Tags("Libraries")]
     [EndpointSummary("Scan library")]
+    [EndpointDescription("Queues a scan of the whole library. Pass ?deep=true for a deep (metadata-refresh) scan.")]
     [ProducesResponseType(StatusCodes.Status202Accepted)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
-    public async Task<IActionResult> ScanLibrary(int id, CancellationToken cancellationToken)
+    public async Task<IActionResult> ScanLibrary(
+        int id,
+        [FromQuery] bool deep = false,
+        CancellationToken cancellationToken = default)
     {
-        QueueLibraryScanResult result = await mediator.Send(new QueueLibraryScanByLibraryId(id), cancellationToken);
+        QueueLibraryScanResult result =
+            await mediator.Send(new QueueLibraryScanByLibraryId(id, deep), cancellationToken);
         return result switch
         {
             QueueLibraryScanResult.Queued => new AcceptedResult(),
@@ -49,19 +55,48 @@ public class LibrariesController(ITelevisionRepository televisionRepository, IMe
     [HttpPost("/api/libraries/{id:int}/scan-show")]
     [Tags("Libraries")]
     [EndpointSummary("Scan show")]
-    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status202Accepted)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
-    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> ScanShow(int id, [FromBody] ScanShowRequest request)
     {
         Option<string> maybeTitle = await televisionRepository.GetShowTitle(id, request.ShowId);
         foreach (string title in maybeTitle)
         {
-            bool result = await mediator.Send(new QueueShowScanByLibraryId(id, request.ShowId, title, request.DeepScan));
+            QueueShowScanResult result =
+                await mediator.Send(new QueueShowScanByLibraryId(id, request.ShowId, title, request.DeepScan));
 
-            return result
-                ? new OkResult()
-                : new BadRequestObjectResult(new { error = "Unable to queue show scan. Library may not exist, may not support single show scanning, or may already be scanning." });
+            return result switch
+            {
+                QueueShowScanResult.Queued => new AcceptedResult(),
+                QueueShowScanResult.AlreadyScanning => ApiResults.ConflictProblem(
+                    "Library scan in progress",
+                    $"A scan for library {id} is already in progress; cannot scan an individual show."),
+                QueueShowScanResult.SyncDisabled => new UnprocessableEntityObjectResult(
+                    new ProblemDetails
+                    {
+                        Status = StatusCodes.Status422UnprocessableEntity,
+                        Title = "Library sync is disabled",
+                        Detail = $"Item sync is disabled for library {id}."
+                    }),
+                QueueShowScanResult.Unsupported => new UnprocessableEntityObjectResult(
+                    new ProblemDetails
+                    {
+                        Status = StatusCodes.Status422UnprocessableEntity,
+                        Title = "Single show scanning is not supported",
+                        Detail = $"Library {id} does not support scanning an individual show."
+                    }),
+                QueueShowScanResult.ScanFailed => new UnprocessableEntityObjectResult(
+                    new ProblemDetails
+                    {
+                        Status = StatusCodes.Status422UnprocessableEntity,
+                        Title = "Unable to scan show",
+                        Detail = $"The scan for show {request.ShowId} in library {id} could not be completed."
+                    }),
+                QueueShowScanResult.NotFound => ApiResults.NotFoundProblem($"Library {id} does not exist."),
+                _ => throw new UnreachableException($"Unmapped QueueShowScanResult: {result}")
+            };
         }
 
         return ApiResults.NotFoundProblem($"Show {request.ShowId} does not exist in library {id}.");

ErsatzTV/Controllers/Api/MaintenanceController.cs

@@ -2,6 +2,7 @@ using System.Threading.Channels;
 using ErsatzTV.Application;
 using ErsatzTV.Application.Maintenance;
 using ErsatzTV.Core;
+using ErsatzTV.Extensions;
 using MediatR;
 using Microsoft.AspNetCore.Mvc;
 
@@ -23,17 +24,14 @@ public class MaintenanceController(IMediator mediator, ChannelWriter<IBackground
     [HttpPost("/api/maintenance/empty_trash")]
     [Tags("Maintenance")]
     [EndpointSummary("Empty trash")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> EmptyTrash()
     {
         Either<BaseError, Unit> result = await mediator.Send(new EmptyTrash());
         foreach (BaseError error in result.LeftToSeq())
         {
-            return new ContentResult
-            {
-                StatusCode = StatusCodes.Status500InternalServerError,
-                Content = error.ToString(),
-                ContentType = "text/plain"
-            };
+            return error.ToErrorResult();
         }
 
         return new OkResult();
@@ -42,9 +40,10 @@ public class MaintenanceController(IMediator mediator, ChannelWriter<IBackground
     [HttpPost("/api/maintenance/clean_artwork")]
     [Tags("Maintenance")]
     [EndpointSummary("Clean artwork cache")]
+    [ProducesResponseType(StatusCodes.Status202Accepted)]
     public async Task<IActionResult> CleanArtwork(CancellationToken cancellationToken)
     {
         await workerChannel.WriteAsync(new DeleteOrphanedArtwork(), cancellationToken);
-        return new OkResult();
+        return new AcceptedResult();
     }
 }

ErsatzTV/Controllers/Api/PlaylistController.cs

@@ -134,6 +134,9 @@ public class PlaylistController(IMediator mediator) : ControllerBase
     [HttpGet("/api/playlists/{id:int}/items", Name = "GetPlaylistItems")]
     [Tags("Playlists")]
     [EndpointSummary("Get the items in a playlist")]
+    [EndpointDescription(
+        "Returns the playlist's items and a strong ETag of the playlist's version. Pass that ETag back " +
+        "as If-Match on the replace (PUT) to detect a concurrent edit (issue #253).")]
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(List<PlaylistItemResponseModel>), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
@@ -145,6 +148,9 @@ public class PlaylistController(IMediator mediator) : ControllerBase
             return ApiResults.NotFoundProblem();
         }
 
+        // The items GET returns children, not the root, so read the playlist's version for the ETag.
+        ConcurrencyHeaders.SetETag(Response, maybePlaylist.Map(p => p.Version).IfNone(0));
+
         List<PlaylistItemViewModel> items = await mediator.Send(new GetPlaylistItems(id), cancellationToken);
         return new OkObjectResult(items.Map(ProjectToItemResponse).ToList());
     }
@@ -168,15 +174,33 @@ public class PlaylistController(IMediator mediator) : ControllerBase
     [HttpPut("/api/playlists/{id:int}", Name = "UpdatePlaylist")]
     [Tags("Playlists")]
     [EndpointSummary("Update a playlist (rename and replace its items)")]
+    [EndpointDescription(
+        "Replaces the playlist's name and its full item list. Item indexes are assigned from the array " +
+        "order. Send the ETag from the items GET as If-Match to reject a stale overwrite with 412 " +
+        "(issue #253); a successful response carries the new ETag.")]
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(List<PlaylistItemResponseModel>), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status412PreconditionFailed)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> Update(
         int id,
         [Required] [FromBody] ReplacePlaylistRequest request,
         CancellationToken cancellationToken)
     {
+        IfMatchCondition ifMatch = ConcurrencyHeaders.ParseIfMatch(Request);
+        if (ifMatch.Kind is IfMatchKind.Malformed)
+        {
+            return new BadRequestObjectResult(
+                new ProblemDetails
+                {
+                    Status = StatusCodes.Status400BadRequest,
+                    Title = "Invalid If-Match header",
+                    Detail = "If-Match must be a strong ETag of the resource version (e.g. \"3\") or \"*\"."
+                });
+        }
+
         Option<PlaylistViewModel> maybePlaylist = await mediator.Send(new GetPlaylistById(id), cancellationToken);
         if (maybePlaylist.IsNone)
         {
@@ -195,10 +219,25 @@ public class PlaylistController(IMediator mediator) : ControllerBase
         }
 
         Either<BaseError, List<PlaylistItemViewModel>> result =
-            await mediator.Send(request.ToCommand(id), cancellationToken);
-        return result.Match(
-            Left: error => error.ToErrorResult(),
-            Right: items => (IActionResult)new OkObjectResult(items.Map(ProjectToItemResponse).ToList()));
+            await mediator.Send(request.ToCommand(id, ifMatch.ExpectedVersion), cancellationToken);
+        return await result.Match(
+            Left: error => Task.FromResult(error.ToErrorResult()),
+            Right: async _ =>
+            {
+                // Reload the root (version) FIRST, then the items, so the emitted ETag is never newer than
+                // the returned items (issue #253 fail-safe ordering; matches BlockController). A None root
+                // (deleted between commit and reload) is a 404, never a 200 without an ETag.
+                Option<PlaylistViewModel> refreshed =
+                    await mediator.Send(new GetPlaylistById(id), cancellationToken);
+                List<PlaylistItemViewModel> items = await mediator.Send(new GetPlaylistItems(id), cancellationToken);
+                return refreshed.Match(
+                    Some: vm =>
+                    {
+                        ConcurrencyHeaders.SetETag(Response, vm.Version);
+                        return (IActionResult)new OkObjectResult(items.Map(ProjectToItemResponse).ToList());
+                    },
+                    None: () => ApiResults.NotFoundProblem());
+            });
     }
 
     [HttpDelete("/api/playlists/{id:int}", Name = "DeletePlaylist")]

ErsatzTV/Controllers/Api/PlayoutController.cs

@@ -69,7 +69,7 @@ public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) :
     public async Task<IActionResult> GetById(int id, CancellationToken cancellationToken)
     {
         Option<PlayoutNameViewModel> result = await mediator.Send(new GetPlayoutById(id), cancellationToken);
-        return result.Map(ToResponse).ToGetResult();
+        return result.Map(vm => ToResponse(vm, entityLocker.IsPlayoutLocked(id))).ToGetResult();
     }
 
     [HttpGet("/api/playouts/{id:int}/items", Name = "GetPlayoutItems")]
@@ -128,7 +128,9 @@ public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) :
                         Option<PlayoutNameViewModel> playout =
                             await mediator.Send(new GetPlayoutById(created.PlayoutId), cancellationToken);
                         return playout.Match(
-                            Some: vm => (IActionResult)new CreatedResult($"/api/playouts/{vm.PlayoutId}", ToResponse(vm)),
+                            Some: vm => (IActionResult)new CreatedResult(
+                                $"/api/playouts/{vm.PlayoutId}",
+                                ToResponse(vm, entityLocker.IsPlayoutLocked(vm.PlayoutId))),
                             None: () => ApiResults.NotFoundProblem());
                     });
             });
@@ -194,7 +196,8 @@ public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) :
 
         return result.Match(
             Left: error => error.ToErrorResult(),
-            Right: playout => (IActionResult)new OkObjectResult(ToResponse(playout)));
+            Right: playout => (IActionResult)new OkObjectResult(
+                ToResponse(playout, entityLocker.IsPlayoutLocked(id))));
     }
 
     private async Task<Either<BaseError, PlayoutNameViewModel>> UpdateScheduleFile(
@@ -260,7 +263,7 @@ public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) :
 
         Option<PlayoutNameViewModel> refreshed = await mediator.Send(new GetPlayoutById(id), cancellationToken);
         return refreshed.Match(
-            Some: vm => (IActionResult)new OkObjectResult(ToResponse(vm)),
+            Some: vm => (IActionResult)new OkObjectResult(ToResponse(vm, entityLocker.IsPlayoutLocked(id))),
             None: () => ApiResults.NotFoundProblem());
     }
 
@@ -583,14 +586,19 @@ public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) :
     [Tags("Playouts")]
     [EndpointSummary("Reset all playouts")]
     [EndpointGroupName("general")]
-    [ProducesResponseType(StatusCodes.Status202Accepted)]
+    [ProducesResponseType(typeof(ResetAllPlayoutsResponseModel), 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.
+    // bulk enqueue, so it always accepts — the 202 body reports which playouts were queued and
+    // which were skipped (locked, or an unsupported ExternalJson/None kind). See docs/decisions.md 2026-07-10.
     public async Task<IActionResult> ResetAll(CancellationToken cancellationToken)
     {
-        await mediator.Send(new ResetAllPlayouts(), cancellationToken);
-        return Accepted();
+        ResetAllPlayoutsResult result = await mediator.Send(new ResetAllPlayouts(), cancellationToken);
+        var body = new ResetAllPlayoutsResponseModel(
+            result.QueuedPlayoutIds,
+            result.SkippedLocked,
+            result.SkippedUnsupported);
+        return new AcceptedResult((string)null, body);
     }
 
     [HttpPost("/api/playouts/{id:int}/erase-items", Name = "ErasePlayoutItems")]
@@ -761,7 +769,7 @@ public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) :
     private static PlayoutHistoryDetailsResponseModel ToDetailsResponse(PlayoutHistoryDetailsViewModel vm) =>
         new(vm.PlaybackOrder, vm.CollectionType, vm.Name, vm.MediaItemType, vm.MediaItemTitle);
 
-    private static PlayoutResponseModel ToResponse(PlayoutNameViewModel vm) =>
+    private static PlayoutResponseModel ToResponse(PlayoutNameViewModel vm, bool isLocked) =>
         PlayoutResponseModel.From(
             vm.PlayoutId,
             vm.ScheduleKind,
@@ -773,7 +781,8 @@ public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) :
             vm.DbDailyRebuildTime,
             ToBuildStatus(vm.BuildStatus),
             vm.DecoId,
-            vm.DecoName);
+            vm.DecoName,
+            isLocked);
 
     private static PlayoutAlternateScheduleResponseModel ToResponse(PlayoutAlternateScheduleViewModel vm) =>
         new(

ErsatzTV/Controllers/Api/PlexMediaSourcesController.cs

@@ -277,6 +277,51 @@ public class PlexMediaSourcesController(
         return new AcceptedResult();
     }
 
+    [HttpPost("/api/media-sources/plex/{id:int}/scan-collections", Name = "ScanPlexCollections")]
+    [Tags("Plex")]
+    [EndpointSummary("Scan a Plex server's collections")]
+    [EndpointDescription(
+        "Queues a synchronization of the server's collections (fire-and-forget). Pass ?deep=true for a deep " +
+        "scan. Returns 409 while a Plex collections scan is already in progress.")]
+    [EndpointGroupName("general")]
+    [ProducesResponseType(StatusCodes.Status202Accepted)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
+    public async Task<IActionResult> ScanCollections(
+        int id,
+        [FromQuery] bool deep = false,
+        CancellationToken cancellationToken = default)
+    {
+        if (!await PlexSourceExists(id, cancellationToken))
+        {
+            return ApiResults.NotFoundProblem();
+        }
+
+        // The collections lock IS the running scan (§3b): fail to acquire = a scan is already active → 409.
+        if (!entityLocker.LockPlexCollections())
+        {
+            return ApiResults.ConflictProblem(
+                "Plex collections scan in progress",
+                "A Plex collections scan is already in progress; try again once it completes.");
+        }
+
+        try
+        {
+            await scannerWorkerChannel.WriteAsync(
+                new SynchronizePlexCollections(id, true, deep),
+                cancellationToken);
+        }
+        catch
+        {
+            // the scanner releases the lock when it processes the message; if the enqueue throws after we
+            // acquired the lock, release it here (EnqueueWithTraktLock compensating-unlock, §3b)
+            entityLocker.UnlockPlexCollections();
+            throw;
+        }
+
+        return new AcceptedResult();
+    }
+
     private async Task<bool> PlexSourceExists(int id, CancellationToken cancellationToken) =>
         (await mediator.Send(new GetPlexMediaSourceById(id), cancellationToken)).IsSome;
 

ErsatzTV/Controllers/Api/Requests/ReplaceDecoTemplateRequest.cs

@@ -4,10 +4,14 @@ namespace ErsatzTV.Controllers.Api.Requests;
 
 public record ReplaceDecoTemplateRequest(string Name, List<DecoTemplateItemRequest> Items)
 {
-    public ReplaceDecoTemplateItems ToCommand(int decoTemplateGroupId, int decoTemplateId) =>
+    public ReplaceDecoTemplateItems ToCommand(
+        int decoTemplateGroupId,
+        int decoTemplateId,
+        Option<int> expectedVersion = default) =>
         new(
             decoTemplateId,
             decoTemplateGroupId,
             Name,
-            (Items ?? []).Select(item => item.ToReplaceItem()).ToList());
+            (Items ?? []).Select(item => item.ToReplaceItem()).ToList(),
+            expectedVersion);
 }

ErsatzTV/Controllers/Api/Requests/ReplacePlaylistRequest.cs

@@ -3,6 +3,7 @@ using System.Collections.Generic;
 using System.Linq;
 using ErsatzTV.Application.MediaCollections;
 using ErsatzTV.Core.Domain;
+using LanguageExt;
 
 namespace ErsatzTV.Controllers.Api.Requests;
 
@@ -56,8 +57,8 @@ public record PlaylistItemRequest(
 
 public record ReplacePlaylistRequest(string? Name, List<PlaylistItemRequest>? Items)
 {
-    public ReplacePlaylistItems ToCommand(int id) =>
-        new(id, Name ?? string.Empty, BuildItems());
+    public ReplacePlaylistItems ToCommand(int id, Option<int> expectedVersion = default) =>
+        new(id, Name ?? string.Empty, BuildItems(), expectedVersion);
 
     // Preview operates on the posted draft, so there is no persisted playlist id (0).
     public ReplacePlaylistItems ToReplaceCommand() =>

ErsatzTV/Controllers/Api/Requests/ReplaceScheduleItemsRequest.cs

@@ -4,8 +4,9 @@ namespace ErsatzTV.Controllers.Api.Requests;
 
 public record ReplaceScheduleItemsRequest(List<ScheduleItemRequest> Items)
 {
-    public ReplaceProgramScheduleItems ToCommand(int scheduleId) =>
+    public ReplaceProgramScheduleItems ToCommand(int scheduleId, Option<int> expectedVersion = default) =>
         new(
             scheduleId,
-            (Items ?? []).Select((item, index) => item.ToReplaceCommand(index)).ToList());
+            (Items ?? []).Select((item, index) => item.ToReplaceCommand(index)).ToList(),
+            expectedVersion);
 }

ErsatzTV/Controllers/Api/Requests/ReplaceTemplateRequest.cs

@@ -4,10 +4,11 @@ namespace ErsatzTV.Controllers.Api.Requests;
 
 public record ReplaceTemplateRequest(string Name, List<TemplateItemRequest> Items)
 {
-    public ReplaceTemplateItems ToCommand(int templateGroupId, int templateId) =>
+    public ReplaceTemplateItems ToCommand(int templateGroupId, int templateId, Option<int> expectedVersion = default) =>
         new(
             templateGroupId,
             templateId,
             Name,
-            (Items ?? []).Select(item => item.ToReplaceItem()).ToList());
+            (Items ?? []).Select(item => item.ToReplaceItem()).ToList(),
+            expectedVersion);
 }

ErsatzTV/Controllers/Api/ScheduleController.cs

@@ -104,7 +104,9 @@ public class ScheduleController(IMediator mediator) : ControllerBase
     [EndpointDescription(
         "Returns the schedule's items plus a computed, best-effort runtime estimate: each item carries a " +
         "nullable durationEstimate and the envelope carries a nullable totalDurationEstimate. Estimates are " +
-        "derived from referenced collection/media runtimes and are null when unbounded or unknown.")]
+        "derived from referenced collection/media runtimes and are null when unbounded or unknown. The " +
+        "response also carries a strong ETag of the schedule's version; pass that ETag back as If-Match on " +
+        "the replace (PUT) to detect a concurrent edit (issue #253).")]
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(ScheduleItemsResponseModel), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
@@ -116,6 +118,9 @@ public class ScheduleController(IMediator mediator) : ControllerBase
             return ApiResults.NotFoundProblem();
         }
 
+        // The items GET returns children, not the root, so read the schedule's version for the ETag.
+        ConcurrencyHeaders.SetETag(Response, schedule.Map(s => s.Version).IfNone(0));
+
         ProgramScheduleItemsWithDurationViewModel items =
             await mediator.Send(new GetProgramScheduleItemsWithDurations(id), cancellationToken);
         return new OkObjectResult(ScheduleItemResponseMapper.ProjectToResponseModel(items));
@@ -143,20 +148,57 @@ public class ScheduleController(IMediator mediator) : ControllerBase
     [HttpPut("/api/schedules/{id:int}/items")]
     [Tags("Schedules")]
     [EndpointSummary("Replace schedule items")]
+    [EndpointDescription(
+        "Replaces the schedule's full item list; item indexes are assigned from the array order. Send the " +
+        "ETag from the items GET as If-Match to reject a stale overwrite with 412 (issue #253); a successful " +
+        "response carries the new ETag.")]
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(List<ScheduleItemResponseModel>), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status412PreconditionFailed)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> ReplaceItems(
         int id,
         [Required] [FromBody] ReplaceScheduleItemsRequest request,
         CancellationToken cancellationToken)
     {
+        IfMatchCondition ifMatch = ConcurrencyHeaders.ParseIfMatch(Request);
+        if (ifMatch.Kind is IfMatchKind.Malformed)
+        {
+            return new BadRequestObjectResult(
+                new ProblemDetails
+                {
+                    Status = StatusCodes.Status400BadRequest,
+                    Title = "Invalid If-Match header",
+                    Detail = "If-Match must be a strong ETag of the resource version (e.g. \"3\") or \"*\"."
+                });
+        }
+
         Either<BaseError, IEnumerable<ProgramScheduleItemViewModel>> result =
-            await mediator.Send(request.ToCommand(id), cancellationToken);
-        return result
-            .Map(items => items.Select(ScheduleItemResponseMapper.ProjectToResponseModel).ToList())
-            .ToUpdatedResult();
+            await mediator.Send(request.ToCommand(id, ifMatch.ExpectedVersion), cancellationToken);
+
+        return await result.Match(
+            Left: error => Task.FromResult(error.ToErrorResult()),
+            Right: async _ =>
+            {
+                // Reload the root (version) FIRST, then the items, so the emitted ETag is never newer than
+                // the returned items (issue #253 fail-safe ordering; matches BlockController). A None root
+                // (deleted between commit and reload) is a 404, never a 200 without an ETag.
+                Option<ProgramScheduleViewModel> refreshed =
+                    await mediator.Send(new GetProgramScheduleById(id), cancellationToken);
+                List<ProgramScheduleItemViewModel> items =
+                    await mediator.Send(new GetProgramScheduleItems(id), cancellationToken);
+                return refreshed.Match(
+                    Some: vm =>
+                    {
+                        // Return the new ETag so a same-tab second save doesn't 412 against its own write.
+                        ConcurrencyHeaders.SetETag(Response, vm.Version);
+                        return (IActionResult)new OkObjectResult(
+                            items.Select(ScheduleItemResponseMapper.ProjectToResponseModel).ToList());
+                    },
+                    None: () => ApiResults.NotFoundProblem());
+            });
     }
 
     [HttpDelete("/api/schedules/{id:int}/items/{itemId:int}")]

ErsatzTV/Controllers/Api/TemplateController.cs

@@ -134,6 +134,9 @@ public class TemplateController(IMediator mediator) : ControllerBase
     [HttpGet("/api/templates/{id:int}/items")]
     [Tags("Templates")]
     [EndpointSummary("Get template items")]
+    [EndpointDescription(
+        "Returns the template's items and a strong ETag of the template's version. Pass that ETag back as " +
+        "If-Match on the replace (PUT) to detect a concurrent edit (issue #253).")]
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(List<TemplateItemResponseModel>), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
@@ -145,6 +148,9 @@ public class TemplateController(IMediator mediator) : ControllerBase
             return ApiResults.NotFoundProblem();
         }
 
+        // The items GET returns children, not the root, so read the template's version for the ETag.
+        ConcurrencyHeaders.SetETag(Response, template.Map(t => t.Version).IfNone(0));
+
         List<TemplateItemViewModel> items = await mediator.Send(new GetTemplateItems(id), cancellationToken);
         return new OkObjectResult(
             items.OrderBy(i => i.StartTime.TimeOfDay).Map(ProjectToResponseModel).ToList());
@@ -155,16 +161,32 @@ public class TemplateController(IMediator mediator) : ControllerBase
     [EndpointSummary("Replace a template and its items")]
     [EndpointDescription(
         "Replaces the template's name and its full item list. Each item assigns a block to a start time of day; " +
-        "items must not overlap (an item's end time is its start time plus the assigned block's duration).")]
+        "items must not overlap (an item's end time is its start time plus the assigned block's duration). " +
+        "Send the ETag from the items GET as If-Match to reject a stale overwrite with 412 (issue #253); " +
+        "a successful response carries the new ETag.")]
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(TemplateWithItemsResponseModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status412PreconditionFailed)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> Replace(
         int id,
         [Required] [FromBody] ReplaceTemplateRequest request,
         CancellationToken cancellationToken)
     {
+        IfMatchCondition ifMatch = ConcurrencyHeaders.ParseIfMatch(Request);
+        if (ifMatch.Kind is IfMatchKind.Malformed)
+        {
+            return new BadRequestObjectResult(
+                new ProblemDetails
+                {
+                    Status = StatusCodes.Status400BadRequest,
+                    Title = "Invalid If-Match header",
+                    Detail = "If-Match must be a strong ETag of the resource version (e.g. \"3\") or \"*\"."
+                });
+        }
+
         Option<TemplateViewModel> maybeTemplate = await mediator.Send(new GetTemplateById(id), cancellationToken);
         if (maybeTemplate.IsNone)
         {
@@ -174,16 +196,25 @@ public class TemplateController(IMediator mediator) : ControllerBase
         int templateGroupId = maybeTemplate.Map(t => t.TemplateGroupId).IfNone(0);
 
         Either<BaseError, List<TemplateItemViewModel>> result =
-            await mediator.Send(request.ToCommand(templateGroupId, id), cancellationToken);
+            await mediator.Send(request.ToCommand(templateGroupId, id, ifMatch.ExpectedVersion), cancellationToken);
 
         return await result.Match(
             Left: error => Task.FromResult(error.ToErrorResult()),
             Right: async _ =>
             {
+                // Reload the root (version) FIRST, then the items, so the emitted ETag is never newer than
+                // the returned items (issue #253 fail-safe ordering; matches BlockController). Returning the
+                // handler's item snapshot alongside a separately re-queried version could pair stale items
+                // with a newer ETag — a client would then silently overwrite the interleaving write.
                 Option<TemplateViewModel> refreshed = await mediator.Send(new GetTemplateById(id), cancellationToken);
                 List<TemplateItemViewModel> items = await mediator.Send(new GetTemplateItems(id), cancellationToken);
                 return refreshed.Match(
-                    Some: vm => (IActionResult)new OkObjectResult(ProjectToWithItemsResponseModel(vm, items)),
+                    Some: vm =>
+                    {
+                        // Return the new ETag so a same-tab second save doesn't 412 against its own write.
+                        ConcurrencyHeaders.SetETag(Response, vm.Version);
+                        return (IActionResult)new OkObjectResult(ProjectToWithItemsResponseModel(vm, items));
+                    },
                     None: () => ApiResults.NotFoundProblem());
             });
     }

ErsatzTV/Controllers/Api/TroubleshootController.cs

@@ -114,7 +114,9 @@ public class TroubleshootController(
     [Tags("Troubleshooting")]
     [EndpointSummary("Start a troubleshooting playback session")]
     [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> TroubleshootPlayback(
         [FromQuery]
         int mediaItem,
@@ -174,9 +176,15 @@ public class TroubleshootController(
                     Optional(start)),
                 cancellationToken);
 
-            if (result.IsLeft)
+            // Distinguish "prepare failed" from the later "no playable output" fall-through: map the
+            // handler's BaseError through the standard helper (404 for NotFoundError — e.g. an unknown
+            // media item/channel — else 422 for a validation failure) with a ProblemDetails body,
+            // instead of a bare body-less 404. The SPA feeds this URL straight to hls.js (HlsPlayer)
+            // and never inspects the status code — failures surface via the /status poll — so the
+            // 404→422 split for validation errors is safe.
+            foreach (BaseError error in result.LeftToSeq())
             {
-                return NotFound();
+                return error.ToErrorResult();
             }
 
             // Prepare returned a process, so the handler holds the troubleshooting lock now
@@ -273,7 +281,12 @@ public class TroubleshootController(
             }
         }
 
-        return NotFound();
+        // Terminal fall-through: Prepare succeeded but no playable output was produced (playback
+        // failed to start, was cancelled, or the segmenter never wrote segments). Keep the 404 status
+        // the SPA player already tolerates, but attach a distinguishing ProblemDetails body rather
+        // than a bare NotFound() so the response is self-describing.
+        return ApiResults.NotFoundProblem(
+            "Troubleshooting playback did not produce any output. It may have failed to start or been cancelled.");
     }
 
     [HttpHead("api/troubleshoot/playback/archive")]