Enforce per-medium track cardinality in the upload service via MediumRules

Promote the Session/Mix single-track rule from a CMS-form convention to a
domain invariant: declare cardinality as data in MediumRules, enforce it in
UnifiedTrackService before the vault write (no orphan), return 409, and read
the same rule in the batch-form collapse.

DeepDrftAPI/Controllers/TrackController.cs

@@ -295,6 +295,15 @@ public class TrackController : ControllerBase
             {
                 var error = result.Messages.FirstOrDefault()?.Message ?? "Failed to process and store audio";
                 _logger.LogWarning("UploadTrack: UnifiedTrackService failed for {TrackName}: {Error}", trackName, error);
+
+                // A cardinality rejection is a well-formed request that violates a domain rule, so it
+                // is 409 Conflict — distinct from the 500 used for processing failure. The marker is
+                // stripped so the client sees only the human-readable detail.
+                if (error.StartsWith(UnifiedTrackService.CardinalityViolationMarker, StringComparison.Ordinal))
+                {
+                    return Conflict(error[UnifiedTrackService.CardinalityViolationMarker.Length..]);
+                }
+
                 return StatusCode(500, error);
             }
 

DeepDrftAPI/Services/UnifiedTrackService.cs

@@ -17,6 +17,14 @@ namespace DeepDrftAPI.Services;
 public class UnifiedTrackService
 {
     internal const string TrackNotFoundMessage = "Track not found.";
+
+    /// <summary>
+    /// Stable marker prefixed onto a cardinality-rejection message so the controller can map this
+    /// specific failure to 409 Conflict (a well-formed request that violates a domain rule),
+    /// distinct from the 400 (malformed) and 500 (processing) paths. The human-readable detail
+    /// follows the marker and is what the CMS surfaces to the admin.
+    /// </summary>
+    internal const string CardinalityViolationMarker = "CARDINALITY_VIOLATION: ";
     private readonly TrackContentService _contentTrackContentService;
     private readonly ITrackService _sqlTrackService;
     private readonly FileDb _fileDatabase;
@@ -57,6 +65,34 @@ public class UnifiedTrackService
         int trackNumber,
         CancellationToken ct)
     {
+        // Cardinality pre-check — BEFORE the vault write so a rejected over-limit add never orphans
+        // audio in the tracks vault. This is a READ-only peek (no release is created for an upload we
+        // may reject); the real FindOrCreateRelease still runs below for the accepted path. Only the
+        // find path can violate: a release that does not yet exist has zero tracks and admits its
+        // first. The guard is the general form `(liveCount + 1) > Max`, not Session/Mix-hardcoded, so
+        // a future bounded medium is covered by the same line.
+        if (!string.IsNullOrWhiteSpace(album))
+        {
+            var peek = await _sqlTrackService.GetReleaseByTitleAndArtist(album, artist, ct);
+            if (!peek.Success)
+            {
+                var error = peek.Messages.FirstOrDefault()?.Message ?? "Unknown error";
+                _logger.LogError("UploadAsync: release peek failed for ({Album}, {Artist}): {Error}", album, artist, error);
+                return ResultContainer<TrackDto>.CreateFailResult($"Could not verify the release: {error}");
+            }
+
+            if (peek.Value is { } existing)
+            {
+                var cardinality = MediumRules.CardinalityOf(existing.Medium);
+                if (existing.TrackCount + 1 > cardinality.Max)
+                {
+                    return ResultContainer<TrackDto>.CreateFailResult(
+                        $"{CardinalityViolationMarker}A {existing.Medium} release holds a single track; " +
+                        $"'{existing.Title}' already has one — edit the existing track or choose a different release.");
+                }
+            }
+        }
+
         var unpersisted = await _contentTrackContentService.AddTrackAsync(
             tempFilePath, trackName, artist, album, genre, releaseDate, originalFileName: originalFileName);