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/entities/__init__.py

@@ -1,7 +1,21 @@
 """Domain entities and value objects — pure, framework-free."""
 
+from app.domain.entities.album import Album
+from app.domain.entities.history import PlayHistoryEntry
+from app.domain.entities.like import Like
+from app.domain.entities.playlist import Playlist
 from app.domain.entities.storage import ObjectStat
 from app.domain.entities.track import Artist, Track
 from app.domain.entities.user import Credentials, User
 
-__all__ = ["Artist", "Credentials", "ObjectStat", "Track", "User"]
+__all__ = [
+    "Album",
+    "Artist",
+    "Credentials",
+    "Like",
+    "ObjectStat",
+    "PlayHistoryEntry",
+    "Playlist",
+    "Track",
+    "User",
+]

app/domain/entities/album.py

@@ -0,0 +1,17 @@
+"""Album domain entity."""
+
+import datetime as dt
+import uuid
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Album:
+    id: uuid.UUID
+    title: str
+    artist_id: uuid.UUID
+    year: int | None
+    cover_path: str | None
+    musicbrainz_id: str | None
+    created_at: dt.datetime
+    updated_at: dt.datetime

app/domain/entities/history.py

@@ -0,0 +1,15 @@
+"""Play history domain entity — append-only scrobble log entry."""
+
+import datetime as dt
+import uuid
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class PlayHistoryEntry:
+    id: uuid.UUID
+    user_id: uuid.UUID
+    track_id: uuid.UUID
+    played_at: dt.datetime
+    play_duration_seconds: int | None
+    completed: bool

app/domain/entities/like.py

@@ -0,0 +1,14 @@
+"""Like domain entity — append-only event log entry."""
+
+import datetime as dt
+import uuid
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Like:
+    id: uuid.UUID
+    user_id: uuid.UUID
+    track_id: uuid.UUID
+    value: str  # "like" | "dislike" | "neutral"
+    created_at: dt.datetime

app/domain/entities/playlist.py

@@ -0,0 +1,16 @@
+"""Playlist domain entity."""
+
+import datetime as dt
+import uuid
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Playlist:
+    id: uuid.UUID
+    name: str
+    description: str | None
+    owner_id: uuid.UUID
+    version: int
+    created_at: dt.datetime
+    updated_at: dt.datetime

app/domain/entities/track.py

@@ -18,12 +18,15 @@ class Track:
     id: uuid.UUID
     title: str
     artist_id: uuid.UUID
+    album_id: uuid.UUID | None
     file_path: str
     file_format: str
     file_size: int
     source: str
     source_id: str
     duration_seconds: int | None
+    genre: str | None
+    year: int | None
     metadata_status: str
     created_at: dt.datetime
     updated_at: dt.datetime

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: ...