feat(sources): local_folder source backend + import pipeline

First ingest path beyond manual upload (plan §1C). Source abstraction +
the first concrete backend, so a homelab can index an existing library.

- domain: SourceBackend/IndexableSource ports + SourceInfo/SourceFile shapes
- infrastructure/sources: LocalFolderSource (walks a mounted dir, idempotent
  source_id = relative path) + registry built from settings
- application: LibraryImportService — batch sibling of UploadService; dedup on
  (source, source_id), copy into storage, minimal track (metadata_status=pending,
  enrichment fills the rest in 1D), per-file failures isolated
- workers: scan_local_folder arq task (registered) + enqueue helper (503 if
  Redis down)
- api: GET /sources, POST /sources/{source}/scan (admin, enqueues), /health
- config: LOCAL_MEDIA_IMPORT_PATH; README + .env.example documented
- tests: scanner, registry, import service (fakes) + DB-gated sources API path

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

app/domain/ports.py

@@ -7,7 +7,7 @@ are bound to these ports at the composition root (``app.api.deps``).
 
 import datetime as dt
 import uuid
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Iterator
 from contextlib import AbstractAsyncContextManager
 from pathlib import Path
 from typing import Protocol
@@ -23,6 +23,7 @@ from app.domain.entities import (
     User,
 )
 from app.domain.entities.track import Artist, Track
+from app.domain.sources import SourceFile, SourceInfo
 from app.domain.tokens import IssuedToken, TokenClaims, TokenType
 
 
@@ -221,3 +222,21 @@ class HistoryRepository(Protocol):
         self, *, user_id: uuid.UUID, limit: int, offset: int
     ) -> list[PlayHistoryEntry]: ...
     async def count(self, *, user_id: uuid.UUID) -> int: ...
+
+
+class SourceBackend(Protocol):
+    """A registered source of tracks (mounted folder, YouTube, …).
+
+    ``name`` is the stable identifier used in URLs and stored on ``track.source``.
+    """
+
+    name: str
+
+    def info(self) -> SourceInfo: ...
+    def is_available(self) -> bool: ...
+
+
+class IndexableSource(SourceBackend, Protocol):
+    """A source that enumerates files already on disk (e.g. the local folder)."""
+
+    def scan(self) -> Iterator[SourceFile]: ...

app/domain/sources.py

@@ -0,0 +1,39 @@
+"""Source-backend value objects — framework-free.
+
+A *source* is a place tracks come from (a mounted folder, YouTube, an upload).
+Backends are driven adapters (``app.infrastructure.sources``); these are the
+shapes they speak in, and the ports they satisfy live in ``app.domain.ports``.
+
+The first backend, ``local``, is *indexable*: it enumerates files already on
+disk. Concrete metadata (artist/album/tags) is intentionally **not** resolved
+here — a source yields a file plus a minimal title; enrichment (plan §6.2) fills
+the rest later, so this stays a thin discovery layer (CLAUDE.md: no duplicated
+business logic)."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class SourceInfo:
+    """Describes a registered source for enumeration / health (UI, admin)."""
+
+    name: str
+    label: str
+    kind: str  # "indexable" (more kinds — search/download — arrive with youtube)
+    available: bool
+
+
+@dataclass(frozen=True, slots=True)
+class SourceFile:
+    """A single importable file discovered by an indexable source.
+
+    ``source_id`` is stable per source (the local backend uses the path relative
+    to its root) so re-scans are idempotent — already-imported files are skipped.
+    """
+
+    source_id: str
+    path: Path
+    suggested_title: str
+    file_format: str
+    file_size: int