feat(library): remote browse status + save/materialize API (§Phase2-3)

Search results now report whether a hit is already saved (in_library,
track_id, availability). New RemoteLibraryService backs POST
/tracks/remote (idempotent placeholder save) and POST
/tracks/{id}/materialize (on-demand fetch via a new materialize_track
arq task, reusing in-flight jobs).

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

app/api/schemas/external_search.py

@@ -1,7 +1,10 @@
 """Schemas for searching external (fetch) sources — the §A4 discover screen."""
 
+import uuid
+
 from pydantic import BaseModel
 
+from app.domain.entities.track import Track
 from app.domain.sources import SearchResult
 
 
@@ -13,9 +16,16 @@ class ExternalSearchResultOut(BaseModel):
     album: str | None
     duration_seconds: int | None
     thumbnail_url: str | None
+    # Remote browse (plan: Model C) — set when this hit is already saved in the
+    # library, so the UI can show "Play"/"Saved" instead of "Save to library".
+    in_library: bool
+    track_id: uuid.UUID | None
+    availability: str | None
 
     @classmethod
-    def from_entity(cls, r: SearchResult) -> ExternalSearchResultOut:
+    def from_entity(
+        cls, r: SearchResult, *, existing: Track | None = None
+    ) -> ExternalSearchResultOut:
         return cls(
             source=r.source,
             source_id=r.source_id,
@@ -24,6 +34,9 @@ class ExternalSearchResultOut(BaseModel):
             album=r.album,
             duration_seconds=r.duration_seconds,
             thumbnail_url=r.thumbnail_url,
+            in_library=existing is not None,
+            track_id=existing.id if existing is not None else None,
+            availability=existing.availability if existing is not None else None,
         )
 
 

app/api/schemas/track.py

@@ -3,7 +3,9 @@
 import datetime as dt
 import uuid
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
+
+from app.api.schemas.download import DownloadJobOut
 
 
 class TrackOut(BaseModel):
@@ -62,3 +64,24 @@ class MetadataApply(BaseModel):
     year: int | None = None
     genre: str | None = None
     track_number: int | None = None
+
+
+class RemoteTrackSave(BaseModel):
+    """Save a remote browse hit (§A4 discover) as a library placeholder —
+    ``availability="remote"``, no audio until first play (plan: Model C)."""
+
+    source: str
+    source_id: str = Field(min_length=1)
+    title: str
+    artist: str | None = None
+
+
+class MaterializeResponse(BaseModel):
+    """Result of requesting that a placeholder track's audio be fetched.
+
+    ``job`` is ``None`` when the track is already ``local`` — nothing to wait
+    for, the caller can stream immediately. Otherwise it's the (new or
+    already in-flight) job; poll ``GET /downloads/{job.id}`` until ``done``."""
+
+    track: TrackOut
+    job: DownloadJobOut | None