Add per-link manual verification for Spotify duration mismatches

Some Spotify matches that read as duration mismatches are intentional —
the wrong-track-on-an-album case where the matcher's automation can't
help, and an admin has manually confirmed the link is correct. Without a
way to record that judgement, the same row reappears on
/admin/duration-mismatches forever and gets re-evaluated by the rematch
sweep on every cycle.

The matcher already honours match_method='manual' as a "do not touch"
flag in update_recording_release_track_id and clear_recording_release_track.
This commit adds the missing producer side: a way to flip the flag from
the admin UI, and the read-side filtering that makes verified rows
disappear from the mismatch reports.

Backend:

- New db helper integrations.spotify.db.set_track_link_manual_override(
    conn, streaming_link_id, manual=True/False)
  flips match_method to 'manual' (or back to 'fuzzy_search' on unverify).
  No schema change — reuses the existing match_method column.

- New admin endpoint POST /admin/duration-mismatches/links/<id>/verify
  with body {"manual": true|false}. 200 + JSON on success, 404 when
  the link doesn't exist. Goes through the existing admin gate +
  CSRF double-submit.

- get_songs_with_duration_mismatches and get_releases_with_duration_mismatches
  in integrations/spotify/db.py now exclude rows where match_method = 'manual'.
  This is the primary effect: the durable rematch sweep
  (rematch_spotify_duration_mismatches.py) stops re-querying confirmed
  matches.

- The /admin/duration-mismatches list page and /admin/duration-mismatches/<song>
  detail page apply the same filter, with an ?include_verified=1 toggle
  for when an admin needs to review or unverify previously-accepted
  rows. The list page additionally shows a banner with the count of
  manually-verified links currently excluded.

Admin UI:

- New "Status" column on the per-song mismatch table with a "Verify"
  button per row. After click, the row reloads with a "Verified" badge
  and an "Unverify" button next to it. Verified rows in include-verified
  mode get a faded background so they visually recede.

- New "Include manually verified mismatches" checkbox above the table
  on both the list page and the per-song page; preserved across
  threshold changes via the URL query.

Tests: 9 new in test_admin_verify_match.py covering the db helper, the
mismatch-query exclusion (both songs and releases helpers), the admin
endpoint's success/unauth/404 paths, and the verify/unverify round trip.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dprodger

backend/integrations/spotify/db.py

@@ -261,6 +261,10 @@ def get_releases_with_duration_mismatches(song_id: str, threshold_ms: int = 6000
                   AND rec.duration_ms IS NOT NULL
                   AND rrsl.duration_ms IS NOT NULL
                   AND ABS(rec.duration_ms - rrsl.duration_ms) > %s
+                  -- Skip rows the admin has manually verified — they're
+                  -- intentionally locked to this Spotify track even when the
+                  -- duration would otherwise look mismatched.
+                  AND (rrsl.match_method IS NULL OR rrsl.match_method != 'manual')
             """
 
             params = [song_id, threshold_ms]
@@ -305,6 +309,8 @@ def get_songs_with_duration_mismatches(threshold_ms: int = 60000) -> List[dict]:
                 WHERE rec.duration_ms IS NOT NULL
                   AND rrsl.duration_ms IS NOT NULL
                   AND ABS(rec.duration_ms - rrsl.duration_ms) > %s
+                  -- Skip admin-verified matches; see get_releases_with_duration_mismatches.
+                  AND (rrsl.match_method IS NULL OR rrsl.match_method != 'manual')
                 ORDER BY s.title
             """, (threshold_ms,))
             return cur.fetchall()
@@ -624,6 +630,44 @@ def is_track_manual_override(conn, recording_release_id: str, service: str = 'sp
         return False
 
 
+def set_track_link_manual_override(conn, streaming_link_id: str,
+                                   manual: bool = True,
+                                   log: logging.Logger = None) -> bool:
+    """Flip a streaming-link row's match_method to/from 'manual'.
+
+    'manual' is the magic value that update_recording_release_track_id
+    and clear_recording_release_track honour as a "do not touch" flag —
+    so once an admin marks a (recording, Spotify track) pair as manually
+    verified, the matcher leaves it alone on every subsequent re-run.
+
+    On unverify (manual=False) the method is reset to 'fuzzy_search';
+    the next matcher pass will re-evaluate from scratch and either
+    re-confirm or replace it. We don't try to remember the previous
+    auto-method — there's no schema slot for it and rediscovery is the
+    correct behaviour.
+
+    Returns True if a row was updated, False if no matching row exists.
+    """
+    log = log or logger
+    new_method = 'manual' if manual else 'fuzzy_search'
+    with conn.cursor() as cur:
+        cur.execute(
+            """
+            UPDATE recording_release_streaming_links
+            SET match_method = %s, updated_at = NOW()
+            WHERE id = %s AND service = 'spotify'
+            """,
+            (new_method, streaming_link_id),
+        )
+        if cur.rowcount == 0:
+            return False
+    log.info(
+        "Streaming link %s match_method set to '%s'",
+        streaming_link_id, new_method,
+    )
+    return True
+
+
 def is_album_manual_override(conn, release_id: str, service: str = 'spotify') -> bool:
     """
     Check if an existing album link is a manual override that should be preserved.

backend/routes/admin.py

@@ -24,7 +24,10 @@
 from integrations.musicbrainz.parsing import parse_release_data
 from integrations.musicbrainz.performer_importer import PerformerImporter
 from integrations.musicbrainz.utils import MusicBrainzSearcher
-from integrations.spotify.db import is_track_manual_override
+from integrations.spotify.db import (
+    is_track_manual_override,
+    set_track_link_manual_override,
+)
 from core.spotify_rematch import (
     run_spotify_rematch_for_song,
     save_run,
@@ -2694,6 +2697,10 @@ def duration_mismatches_list():
     threshold = request.args.get('threshold', 60, type=int)
     current_sort = request.args.get('sort', 'mismatch_count')
     current_order = request.args.get('order', 'desc')
+    # ?include_verified=1 to also count rows the admin has manually
+    # verified (match_method='manual'). Default-off so the page is a
+    # signal of work-still-to-do, not a rehash of accepted overrides.
+    include_verified = request.args.get('include_verified') in ('1', 'true', 'yes')
     threshold_ms = threshold * 1000
 
     sort_map = {
@@ -2704,6 +2711,11 @@ def duration_mismatches_list():
     order_col = sort_map.get(current_sort, 'mismatch_count')
     order_dir = 'ASC' if current_order == 'asc' else 'DESC'
 
+    manual_filter = (
+        '' if include_verified
+        else "AND (rrsl.match_method IS NULL OR rrsl.match_method != 'manual')"
+    )
+
     with get_db_connection() as db:
         with db.cursor() as cur:
             cur.execute(f"""
@@ -2723,6 +2735,7 @@ def duration_mismatches_list():
                 WHERE r.duration_ms IS NOT NULL
                   AND rrsl.duration_ms IS NOT NULL
                   AND ABS(r.duration_ms - rrsl.duration_ms) > %s
+                  {manual_filter}
                 GROUP BY s.id, s.title, s.composer
                 ORDER BY {order_col} {order_dir}, s.title ASC
             """, (threshold_ms,))
@@ -2739,12 +2752,21 @@ def duration_mismatches_list():
             """)
             total_spotify = cur.fetchone()['cnt']
 
+            cur.execute("""
+                SELECT COUNT(*) AS cnt
+                FROM recording_release_streaming_links
+                WHERE service = 'spotify' AND match_method = 'manual'
+            """)
+            total_manual = cur.fetchone()['cnt']
+
             total_mismatched = sum(s['mismatch_count'] for s in songs)
 
     summary = {
         'total_songs': len(songs),
         'total_mismatched_links': total_mismatched,
         'total_spotify_links': total_spotify,
+        'total_manual_links': total_manual,
+        'include_verified': include_verified,
     }
 
     return render_template('admin/duration_mismatches_list.html',
@@ -2759,8 +2781,14 @@ def duration_mismatches_list():
 def duration_mismatches_review(song_id):
     """Review duration mismatches for a specific song"""
     threshold = request.args.get('threshold', 60, type=int)
+    include_verified = request.args.get('include_verified') in ('1', 'true', 'yes')
     threshold_ms = threshold * 1000
 
+    manual_filter = (
+        '' if include_verified
+        else "AND (rrsl.match_method IS NULL OR rrsl.match_method != 'manual')"
+    )
+
     with get_db_connection() as db:
         with db.cursor() as cur:
             cur.execute("""
@@ -2772,7 +2800,7 @@ def duration_mismatches_review(song_id):
                 return "Song not found", 404
             song = dict(song)
 
-            cur.execute("""
+            cur.execute(f"""
                 SELECT
                     r.id AS recording_id,
                     r.title,
@@ -2805,6 +2833,7 @@ def duration_mismatches_review(song_id):
                   AND r.duration_ms IS NOT NULL
                   AND rrsl.duration_ms IS NOT NULL
                   AND ABS(r.duration_ms - rrsl.duration_ms) > %s
+                  {manual_filter}
                 ORDER BY r.recording_year NULLS LAST, rel.title
             """, (song_id, threshold_ms))
             rows = [dict(row) for row in cur.fetchall()]
@@ -2838,6 +2867,7 @@ def duration_mismatches_review(song_id):
             'diff_display': _format_diff(diff_ms),
             'match_confidence': float(row['match_confidence']) if row['match_confidence'] is not None else None,
             'match_method': row['match_method'],
+            'is_manual': row['match_method'] == 'manual',
             'release_title': row['release_title'],
             'artist_credit': row['artist_credit'],
             'release_mb_id': row['release_mb_id'],
@@ -2851,7 +2881,8 @@ def duration_mismatches_review(song_id):
     return render_template('admin/duration_mismatches_review.html',
                            song=song,
                            recordings=recordings,
-                           threshold=threshold)
+                           threshold=threshold,
+                           include_verified=include_verified)
 
 
 @admin_bp.route('/duration-mismatches/delete-links', methods=['POST'])
@@ -2887,6 +2918,42 @@ def duration_mismatches_delete():
         return jsonify({'error': str(e)}), 500
 
 
+@admin_bp.route('/duration-mismatches/links/<link_id>/verify', methods=['POST'])
+def duration_mismatches_verify_link(link_id):
+    """Mark a Spotify streaming link as manually verified (or un-verify it).
+
+    Flips `recording_release_streaming_links.match_method` to 'manual',
+    which is the magic value the matcher already honours as a "do not
+    touch" flag in update_recording_release_track_id and
+    clear_recording_release_track. The duration-mismatch admin queries
+    also exclude rows with match_method='manual' so the UI stops nagging
+    about a match the admin has already accepted.
+
+    Body: optional JSON {"manual": false} to revert. Default is to set
+    manual=true.
+    """
+    data = request.get_json(silent=True) or {}
+    set_manual = bool(data.get('manual', True))
+    try:
+        with get_db_connection() as db:
+            updated = set_track_link_manual_override(
+                db, link_id, manual=set_manual, log=logger,
+            )
+            db.commit()
+    except Exception as e:
+        logger.error(f"Error toggling manual override on link {link_id}: {e}")
+        return jsonify({'error': str(e)}), 500
+
+    if not updated:
+        return jsonify({'error': 'Streaming link not found'}), 404
+
+    return jsonify({
+        'success': True,
+        'link_id': link_id,
+        'match_method': 'manual' if set_manual else 'fuzzy_search',
+    })
+
+
 @admin_bp.route('/users')
 def users_list():
     """List user accounts with email search and pagination."""

backend/templates/admin/duration_mismatches_list.html

@@ -231,9 +231,25 @@ <h1>Spotify Duration Mismatches</h1>
                     <option value="desc" {% if current_order == 'desc' %}selected{% endif %}>Descending</option>
                 </select>
             </div>
+            <div class="filter-group">
+                <label>&nbsp;</label>
+                <label style="font-weight: normal; display: flex; align-items: center; gap: 6px;">
+                    <input type="checkbox" name="include_verified" value="1"
+                           {% if summary.include_verified %}checked{% endif %}>
+                    Include verified matches
+                </label>
+            </div>
             <button type="submit" class="apply-btn">Apply</button>
         </form>
 
+        {% if summary.total_manual_links %}
+        <p style="font-size: 13px; color: #666; margin-top: -8px;">
+            {{ summary.total_manual_links }} Spotify link(s) are manually
+            verified and excluded from this report
+            {% if summary.include_verified %}<em>(currently included)</em>{% else %}— check the box above to include them{% endif %}.
+        </p>
+        {% endif %}
+
         <!-- Results Table -->
         {% if songs %}
         <table>
@@ -249,7 +265,7 @@ <h1>Spotify Duration Mismatches</h1>
                 {% for song in songs %}
                 <tr>
                     <td>
-                        <a href="{{ admin_url('/admin/duration-mismatches/') }}{{ song.song_id }}?threshold={{ threshold }}" class="song-link">
+                        <a href="{{ admin_url('/admin/duration-mismatches/') }}{{ song.song_id }}?threshold={{ threshold }}{% if summary.include_verified %}&include_verified=1{% endif %}" class="song-link">
                             <div class="song-title">{{ song.title }}</div>
                             {% if song.composer %}
                             <div class="composer">{{ song.composer }}</div>