Persist selected YouTube candidate truth

docs/spooty-operations-snapshot.md

@@ -6,6 +6,7 @@ The MVP reports truth Spooty already owns without a schema migration:
 
 - track state from `TrackEntity.status`
 - selected YouTube URL from `TrackEntity.youtubeUrl`
+- selected YouTube candidate title, author, score, and reason from `TrackEntity`
 - raw failure evidence from `TrackEntity.error`
 - download retry count from `TrackEntity.downloadAttemptCount`
 - rejected YouTube candidates from `TrackEntity.rejectedYoutubeUrls`
@@ -13,11 +14,10 @@ The MVP reports truth Spooty already owns without a schema migration:
 - queue depth and active jobs from BullMQ queues `track-search-processor` and `track-download-processor`
 - Spotify connection presence from the stored Spotify user token
 
-The endpoint intentionally does not infer candidate scoring history. Today, selected candidate title, author, score, and reason are logged during search but are not persisted. Rejected candidates are persisted only as URL strings.
+The endpoint intentionally does not infer candidate scoring history. Selected candidate metadata is persisted when Spooty chooses a candidate. Rejected candidates are still persisted only as URL strings.
 
 Future persistence work is required for:
 
-- selected candidate title, author, score, and scoring reason
 - full searched candidate history
 - structured rejected candidate metadata beyond URL
 - structured error class fields stored at write time instead of classified from the persisted raw error string

src/backend/src/operations/operations.service.ts

@@ -176,6 +176,25 @@ export class OperationsService {
       status: TrackStatusEnum[track.status] || String(track.status),
       ...(track.spotifyUrl ? { spotifyUrl: track.spotifyUrl } : {}),
       ...(track.youtubeUrl ? { youtubeUrl: track.youtubeUrl } : {}),
+      ...(track.youtubeUrl
+        ? {
+            selectedCandidate: {
+              url: track.youtubeUrl,
+              ...(track.selectedYoutubeTitle
+                ? { title: track.selectedYoutubeTitle }
+                : {}),
+              ...(track.selectedYoutubeAuthor
+                ? { author: track.selectedYoutubeAuthor }
+                : {}),
+              ...(typeof track.selectedYoutubeScore === 'number'
+                ? { score: track.selectedYoutubeScore }
+                : {}),
+              ...(track.selectedYoutubeReason
+                ? { reason: track.selectedYoutubeReason }
+                : {}),
+            },
+          }
+        : {}),
       ...(typeof track.downloadAttemptCount === 'number'
         ? { downloadAttemptCount: track.downloadAttemptCount }
         : {}),

src/backend/src/operations/operations.types.ts

@@ -23,6 +23,13 @@ export interface TrackTruth {
   status: string;
   spotifyUrl?: string;
   youtubeUrl?: string;
+  selectedCandidate?: {
+    url: string;
+    title?: string;
+    author?: string;
+    score?: number;
+    reason?: string;
+  };
   downloadAttemptCount?: number;
   errorClass?: ErrorClass;
   errorSummary?: string;

src/backend/src/track/track.entity.ts

@@ -27,6 +27,18 @@ export class TrackEntity {
   @Column({ nullable: true })
   youtubeUrl?: string;
 
+  @Column({ nullable: true })
+  selectedYoutubeTitle?: string;
+
+  @Column({ nullable: true })
+  selectedYoutubeAuthor?: string;
+
+  @Column({ nullable: true })
+  selectedYoutubeScore?: number;
+
+  @Column({ nullable: true, type: 'text' })
+  selectedYoutubeReason?: string;
+
   @Column({ nullable: true, type: 'text' })
   rejectedYoutubeUrls?: string;
 

src/backend/src/track/track.service.ts

@@ -98,7 +98,9 @@ export class TrackService {
 
     try {
       const parsed = JSON.parse(track.rejectedYoutubeUrls);
-      return Array.isArray(parsed) ? parsed.filter((item) => typeof item === 'string') : [];
+      return Array.isArray(parsed)
+        ? parsed.filter((item) => typeof item === 'string')
+        : [];
     } catch {
       return [];
     }
@@ -125,6 +127,10 @@ export class TrackService {
     await this.update(id, {
       ...track,
       youtubeUrl: null,
+      selectedYoutubeTitle: null,
+      selectedYoutubeAuthor: null,
+      selectedYoutubeScore: null,
+      selectedYoutubeReason: null,
       rejectedYoutubeUrls: this.stringifyRejectedYoutubeUrls(rejectedUrls),
       downloadAttemptCount: 0,
       error: null,
@@ -161,6 +167,10 @@ export class TrackService {
       updatedTrack = {
         ...track,
         youtubeUrl: youtubeMatch.url,
+        selectedYoutubeTitle: youtubeMatch.title,
+        selectedYoutubeAuthor: youtubeMatch.author,
+        selectedYoutubeScore: youtubeMatch.score,
+        selectedYoutubeReason: youtubeMatch.reason,
         status: TrackStatusEnum.Queued,
       };
       this.logger.debug(
@@ -193,7 +203,9 @@ export class TrackService {
     const existingJob = await this.trackSearchQueue.getJob(jobId);
 
     if (existingJob) {
-      this.logger.warn(`Removing existing search job for track ${id} before enqueue`);
+      this.logger.warn(
+        `Removing existing search job for track ${id} before enqueue`,
+      );
       await existingJob.remove();
     }
 
@@ -212,7 +224,9 @@ export class TrackService {
     const existingJob = await this.trackDownloadQueue.getJob(jobId);
 
     if (existingJob) {
-      this.logger.warn(`Removing existing download job for track ${id} before enqueue`);
+      this.logger.warn(
+        `Removing existing download job for track ${id} before enqueue`,
+      );
       await existingJob.remove();
     }
 
@@ -296,6 +310,10 @@ export class TrackService {
       await this.update(track.id, {
         ...track,
         youtubeUrl: null,
+        selectedYoutubeTitle: null,
+        selectedYoutubeAuthor: null,
+        selectedYoutubeScore: null,
+        selectedYoutubeReason: null,
         rejectedYoutubeUrls: this.stringifyRejectedYoutubeUrls(rejectedUrls),
         downloadAttemptCount: nextAttemptCount,
         error: null,
@@ -320,7 +338,8 @@ export class TrackService {
     const safeArtist = track.artist || 'unknown_artist';
     const safeName = track.name || 'unknown_track';
     const fileName = `${safeArtist} - ${safeName}`;
-    const format = this.configService.get<string>(EnvironmentEnum.FORMAT) || 'mp3';
+    const format =
+      this.configService.get<string>(EnvironmentEnum.FORMAT) || 'mp3';
     return `${this.utilsService.stripFileIllegalChars(fileName)}.${format}`;
   }