fix: preserve album track order during ATProto sync (#592)

* fix: preserve album track order during ATProto sync (#587)

when syncing album list records to ATProto, the background sync was
always ordering tracks by created_at, overwriting any custom order
the user had set via the frontend reorder feature.

now the sync:
1. fetches the existing ATProto list record order (if any)
2. preserves that order for existing tracks
3. appends any new tracks at the end (sorted by created_at)

this prevents user-reordered albums from reverting on login.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

* fix: use unique DID and cleanup in test to avoid CI conflicts

the test was sharing fixtures with fixed DIDs causing foreign key
constraint violations during teardown when running in parallel with xdist.

now uses:
- unique DID with uuid suffix for test isolation
- explicit cleanup in finally block (tracks → albums → artists order)
- properly typed capture function for lint compliance

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

---------

Co-authored-by: Claude Opus 4.5 <[e-mail]>

backend/src/backend/_internal/atproto/sync.py

···
 
 from backend._internal import Session as AuthSession
 from backend._internal.atproto.records.fm_plyr import (
+    get_record_public,
     upsert_album_list_record,
     upsert_liked_list_record,
     upsert_profile_record,
···
 logger = logging.getLogger(__name__)
 
 
+async def _get_existing_track_order(
+    album_atproto_uri: str,
+    artist_pds_url: str | None,
+) -> list[str]:
+    """fetch existing track URIs from ATProto list record.
+
+    returns list of track URIs in the order stored in ATProto,
+    or empty list if fetch fails.
+    """
+    if not album_atproto_uri or not artist_pds_url:
+        return []
+
+    try:
+        record_data = await get_record_public(
+            record_uri=album_atproto_uri,
+            pds_url=artist_pds_url,
+        )
+        items = record_data.get("value", {}).get("items", [])
+        return [
+            item.get("subject", {}).get("uri")
+            for item in items
+            if item.get("subject", {}).get("uri")
+        ]
+    except Exception as e:
+        logger.debug(f"could not fetch existing ATProto record order: {e}")
+        return []
+
+
 async def sync_atproto_records(
     auth_session: AuthSession,
     user_did: str,
···
 
     # query and sync album list records
     async with db_session() as session:
+        # fetch artist for PDS URL (needed for ATProto record fetch)
+        artist_result = await session.execute(
+            select(Artist).where(Artist.did == user_did)
+        )
+        artist = artist_result.scalar_one_or_none()
+        artist_pds_url = artist.pds_url if artist else None
+
         albums_result = await session.execute(
             select(Album).where(Album.artist_did == user_did)
         )
···
 
         for album in albums:
             tracks_result = await session.execute(
-                select(Track)
-                .where(
+                select(Track).where(
                     Track.album_id == album.id,
                     Track.atproto_record_uri.isnot(None),
                     Track.atproto_record_cid.isnot(None),
                 )
-                .order_by(Track.created_at.asc())
             )
-            tracks = tracks_result.scalars().all()
+            tracks = list(tracks_result.scalars().all())
 
             if tracks:
+                # if album has existing ATProto record, preserve its track order
+                # this prevents overwriting user's custom reordering
+                existing_order = await _get_existing_track_order(
+                    album.atproto_record_uri, artist_pds_url
+                )
+
+                if existing_order:
+                    # order tracks by existing ATProto order, append new tracks at end
+                    track_by_uri = {t.atproto_record_uri: t for t in tracks}
+                    ordered_tracks = []
+                    seen_uris = set()
+
+                    # first: tracks in existing order
+                    for uri in existing_order:
+                        if uri in track_by_uri:
+                            ordered_tracks.append(track_by_uri[uri])
+                            seen_uris.add(uri)
+
+                    # then: any new tracks not in existing order (by created_at)
+                    new_tracks = [
+                        t for t in tracks if t.atproto_record_uri not in seen_uris
+                    ]
+                    new_tracks.sort(key=lambda t: t.created_at)
+                    ordered_tracks.extend(new_tracks)
+
+                    tracks = ordered_tracks
+                else:
+                    # no existing order - use created_at (default for new albums)
+                    tracks.sort(key=lambda t: t.created_at)
+
                 track_refs = [
                     {"uri": t.atproto_record_uri, "cid": t.atproto_record_cid}
                     for t in tracks

backend/tests/api/test_list_record_sync.py

···
         await sync_atproto_records(mock_session, "did:plc:testartist123")
 
 
+async def test_sync_preserves_existing_album_track_order(
+    db_session: AsyncSession,
+):
+    """test that sync preserves user's custom track order from ATProto.
+
+    regression test for issue #587: album track reorder reverts.
+    when an album already has an ATProto list record with a custom order,
+    sync should preserve that order instead of overwriting with created_at.
+    """
+    import uuid
+    from datetime import UTC, datetime, timedelta
+
+    from sqlalchemy import delete
+
+    from backend._internal.atproto import sync_atproto_records
+
+    # use unique DID to avoid conflicts with other tests
+    unique_did = f"did:plc:ordertest{uuid.uuid4().hex[:8]}"
+
+    # create artist with pds_url (required for ATProto record fetch)
+    artist = Artist(
+        did=unique_did,
+        handle="ordertest.bsky.social",
+        display_name="Order Test Artist",
+        pds_url="https://test.pds",
+    )
+    db_session.add(artist)
+    await db_session.flush()
+
+    # create album with existing ATProto record
+    album = Album(
+        artist_did=unique_did,
+        title="Reordered Album",
+        slug="reordered-album",
+        atproto_record_uri=f"at://{unique_did}/fm.plyr.list/existing123",
+        atproto_record_cid="bafyexisting123",
+    )
+    db_session.add(album)
+    await db_session.flush()
+
+    # create tracks with staggered created_at (track3 oldest, track1 newest)
+    base_time = datetime.now(UTC)
+    track1 = Track(
+        title="Track 1",
+        file_id=f"preserve-order-1-{uuid.uuid4().hex[:8]}",
+        file_type="audio/mpeg",
+        artist_did=unique_did,
+        album_id=album.id,
+        atproto_record_uri=f"at://{unique_did}/fm.plyr.track/t1",
+        atproto_record_cid="cid1",
+        created_at=base_time,  # newest
+    )
+    track2 = Track(
+        title="Track 2",
+        file_id=f"preserve-order-2-{uuid.uuid4().hex[:8]}",
+        file_type="audio/mpeg",
+        artist_did=unique_did,
+        album_id=album.id,
+        atproto_record_uri=f"at://{unique_did}/fm.plyr.track/t2",
+        atproto_record_cid="cid2",
+        created_at=base_time - timedelta(hours=1),
+    )
+    track3 = Track(
+        title="Track 3",
+        file_id=f"preserve-order-3-{uuid.uuid4().hex[:8]}",
+        file_type="audio/mpeg",
+        artist_did=unique_did,
+        album_id=album.id,
+        atproto_record_uri=f"at://{unique_did}/fm.plyr.track/t3",
+        atproto_record_cid="cid3",
+        created_at=base_time - timedelta(hours=2),  # oldest
+    )
+    db_session.add_all([track1, track2, track3])
+    await db_session.commit()
+
+    album_id = album.id
+    mock_session = MockSession(did=unique_did)
+
+    # mock ATProto record fetch to return custom order: track2, track1, track3
+    # (user reordered via frontend - different from created_at order)
+    mock_existing_record = {
+        "value": {
+            "items": [
+                {"subject": {"uri": track2.atproto_record_uri, "cid": "cid2"}},
+                {"subject": {"uri": track1.atproto_record_uri, "cid": "cid1"}},
+                {"subject": {"uri": track3.atproto_record_uri, "cid": "cid3"}},
+            ]
+        }
+    }
+
+    captured_track_refs: list[dict[str, str]] = []
+
+    async def capture_album_sync(*args: object, **kwargs: object) -> tuple[str, str]:
+        track_refs: list[dict[str, str]] = kwargs.get("track_refs", [])  # type: ignore[assignment]
+        captured_track_refs.extend(track_refs)
+        assert album.atproto_record_uri is not None
+        return (album.atproto_record_uri, "bafynewcid")
+
+    try:
+        with (
+            patch(
+                "backend._internal.atproto.sync.upsert_profile_record",
+                new_callable=AsyncMock,
+                return_value=None,
+            ),
+            patch(
+                "backend._internal.atproto.sync.get_record_public",
+                new_callable=AsyncMock,
+                return_value=mock_existing_record,
+            ),
+            patch(
+                "backend._internal.atproto.sync.upsert_album_list_record",
+                new_callable=AsyncMock,
+                side_effect=capture_album_sync,
+            ),
+            patch(
+                "backend._internal.atproto.sync.upsert_liked_list_record",
+                new_callable=AsyncMock,
+                return_value=None,
+            ),
+        ):
+            await sync_atproto_records(mock_session, unique_did)
+
+        # verify track order was preserved (track2, track1, track3)
+        # NOT created_at order (which would be track3, track2, track1)
+        assert len(captured_track_refs) == 3
+        assert captured_track_refs[0]["uri"] == track2.atproto_record_uri
+        assert captured_track_refs[1]["uri"] == track1.atproto_record_uri
+        assert captured_track_refs[2]["uri"] == track3.atproto_record_uri
+    finally:
+        # clean up in correct order (tracks before albums before artists)
+        await db_session.execute(delete(Track).where(Track.album_id == album_id))
+        await db_session.execute(delete(Album).where(Album.id == album_id))
+        await db_session.execute(delete(Artist).where(Artist.did == unique_did))
+        await db_session.commit()
+
+
 async def test_login_callback_triggers_background_sync(
     test_app: FastAPI,
     db_session: AsyncSession,