feat: implement 1B domain entities/repos + 1H library API routes

1B — domain layer:
- New entities: Album, Playlist, Like, PlayHistoryEntry
- Track entity extended with album_id, genre, year fields
- New protocols: AlbumRepository, PlaylistRepository, LikeRepository, HistoryRepository
- ArtistRepository / TrackRepository protocols extended (list, count, update, get_many, etc.)
- New repos: SqlAlchemyAlbum/Playlist/Like/HistoryRepository
- Artist and track repos updated to match extended protocols

1H — library API:
- Pagination: PagedResponse[T] generic, offset-based, limit default 50 max 200
- Schemas: TrackOut, AlbumOut, ArtistOut, PlaylistOut/Create/Update,
  LikeEvent/State, HistoryIn/Out, LibrarySearchResponse
- GET/PATCH/DELETE /tracks with filters, sort, pagination
- GET /albums, /albums/{id}, /albums/{id}/tracks
- GET /artists, /artists/{id}, /artists/{id}/albums, /artists/{id}/tracks
- GET /search/library (ILIKE across tracks/albums/artists)
- Full /playlists CRUD + track add/remove (append-only version bump)
- POST /likes (append-only event log), GET /likes, GET /likes/state
- POST /history (scrobble), GET /history
- deps.py: TrackRepoDep, ArtistRepoDep, AlbumRepoDep, PlaylistRepoDep,
  LikeRepoDep, HistoryRepoDep

ruff ✅  mypy ✅  pytest 45/45 ✅

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

app/domain/ports.py

@@ -12,7 +12,15 @@ from contextlib import AbstractAsyncContextManager
 from pathlib import Path
 from typing import Protocol
 
-from app.domain.entities import Credentials, ObjectStat, User
+from app.domain.entities import (
+    Album,
+    Credentials,
+    Like,
+    ObjectStat,
+    PlayHistoryEntry,
+    Playlist,
+    User,
+)
 from app.domain.entities.track import Artist, Track
 from app.domain.tokens import IssuedToken, TokenClaims, TokenType
 
@@ -75,6 +83,12 @@ class FileStorage(Protocol):
 
 class ArtistRepository(Protocol):
     async def get_or_create(self, name: str) -> Artist: ...
+    async def get_by_id(self, artist_id: uuid.UUID) -> Artist | None: ...
+    async def get_many(self, ids: list[uuid.UUID]) -> list[Artist]: ...
+    async def list(self, *, q: str | None, limit: int, offset: int) -> list[Artist]: ...
+    async def count(self, *, q: str | None) -> int: ...
+    async def album_count(self, artist_id: uuid.UUID) -> int: ...
+    async def track_count(self, artist_id: uuid.UUID) -> int: ...
 
 
 class TrackRepository(Protocol):
@@ -95,3 +109,91 @@ class TrackRepository(Protocol):
         added_by: uuid.UUID | None,
     ) -> Track: ...
     async def delete(self, track_id: uuid.UUID) -> None: ...
+    async def list(
+        self,
+        *,
+        artist_id: uuid.UUID | None,
+        album_id: uuid.UUID | None,
+        q: str | None,
+        sort_by: str,
+        order: str,
+        limit: int,
+        offset: int,
+    ) -> list[Track]: ...
+    async def count(
+        self,
+        *,
+        artist_id: uuid.UUID | None,
+        album_id: uuid.UUID | None,
+        q: str | None,
+    ) -> int: ...
+    async def update(
+        self,
+        track_id: uuid.UUID,
+        *,
+        title: str | None,
+        genre: str | None,
+        year: int | None,
+    ) -> Track: ...
+
+
+class AlbumRepository(Protocol):
+    async def get_by_id(self, album_id: uuid.UUID) -> Album | None: ...
+    async def get_many(self, ids: list[uuid.UUID]) -> list[Album]: ...
+    async def count(self, *, artist_id: uuid.UUID | None, q: str | None) -> int: ...
+    async def track_count(self, album_id: uuid.UUID) -> int: ...
+    async def track_count_many(self, album_ids: list[uuid.UUID]) -> dict[uuid.UUID, int]: ...
+    # list must come after any method using list[...] in its signature (name shadowing)
+    async def list(
+        self, *, artist_id: uuid.UUID | None, q: str | None, limit: int, offset: int
+    ) -> list[Album]: ...
+
+
+class PlaylistRepository(Protocol):
+    async def get_by_id(self, playlist_id: uuid.UUID) -> Playlist | None: ...
+    async def count(self, *, owner_id: uuid.UUID) -> int: ...
+    async def add(self, *, name: str, description: str | None, owner_id: uuid.UUID) -> Playlist: ...
+    async def update(
+        self, playlist_id: uuid.UUID, *, name: str | None, description: str | None
+    ) -> Playlist: ...
+    async def delete(self, playlist_id: uuid.UUID) -> None: ...
+    async def track_count(self, playlist_id: uuid.UUID) -> int: ...
+    async def track_count_many(self, playlist_ids: list[uuid.UUID]) -> dict[uuid.UUID, int]: ...
+    async def get_tracks(
+        self, playlist_id: uuid.UUID, *, limit: int, offset: int
+    ) -> list[Track]: ...
+    async def get_track_total(self, playlist_id: uuid.UUID) -> int: ...
+    async def add_track(
+        self, playlist_id: uuid.UUID, track_id: uuid.UUID, *, position: float
+    ) -> None: ...
+    async def remove_track(self, playlist_id: uuid.UUID, track_id: uuid.UUID) -> None: ...
+    async def max_position(self, playlist_id: uuid.UUID) -> float: ...
+    # list must come after any method using list[...] in its signature (name shadowing)
+    async def list(self, *, owner_id: uuid.UUID, limit: int, offset: int) -> list[Playlist]: ...
+
+
+class LikeRepository(Protocol):
+    async def add(self, *, user_id: uuid.UUID, track_id: uuid.UUID, value: str) -> Like: ...
+    async def get_latest_state(
+        self, *, user_id: uuid.UUID, track_ids: list[uuid.UUID]
+    ) -> list[Like]: ...
+    async def list_liked_tracks(
+        self, *, user_id: uuid.UUID, limit: int, offset: int
+    ) -> list[Track]: ...
+    async def count_liked_tracks(self, *, user_id: uuid.UUID) -> int: ...
+
+
+class HistoryRepository(Protocol):
+    async def add(
+        self,
+        *,
+        user_id: uuid.UUID,
+        track_id: uuid.UUID,
+        played_at: dt.datetime,
+        play_duration_seconds: int | None,
+        completed: bool,
+    ) -> PlayHistoryEntry: ...
+    async def list(
+        self, *, user_id: uuid.UUID, limit: int, offset: int
+    ) -> list[PlayHistoryEntry]: ...
+    async def count(self, *, user_id: uuid.UUID) -> int: ...