docs: add tagging, import & persistent library plan (slice 1, plan 4b)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-10 23:41:46 +02:00
parent fef8cf0681
commit 6cce95cec6
1 changed files with 643 additions and 0 deletions
@@ -0,0 +1,643 @@
+# Lyra Tagging, Import & Persistent Library Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Finish slice 1 by turning a completed download into a real library entry: persist `/music` to a host folder (so downloads survive container recreation), organize files into `Artist/Album (Year)/` with filesystem-safe names, and tag each track with canonical MusicBrainz metadata (mutagen) renamed to `## Title.ext`.
+
+**Architecture:** A pure `library` module computes the album directory and safe names (fully unit-testable). The pipeline's download stage writes into that directory; the tag stage, after the completeness check, calls an injectable `Tagger` seam. Tests use a `FakeTagger`; the real `MutagenTagger` (writes tags + renames via mutagen) is covered by an opt-in test. The resolver is extended to return the per-track titles (`MBTarget.tracklist`). Everything is backward-compatible: `run_pipeline` gains `tagger=None`, and with no tagger the tag stage just skips tagging as today.
+
+**Tech Stack:** Python 3.12 worker; `mutagen` (new dependency). Tests: pytest (pure layout logic offline + fake tagger) + an opt-in real-tagging test gated by `LYRA_LIVE_TESTS`. Docker Compose bind-mount for `/music`.
+
+## Global Constraints
+
+- Python 3.12 in the worker container; version-flexible local deps.
+- **New dependency:** `mutagen` (pure-Python, lightweight). Imported LAZILY inside the real tagger's method so importing the module / constructing the tagger stays offline. No other new deps.
+- `ranker`/`confidence`/`quality`/adapters/resolver-seam UNCHANGED except: `types.py` gains `MBTarget.tracklist`, `_musicbrainz.py` fills it. Pipeline changes are confined to the download-dest computation and the tag stage.
+- **Backward compatibility is mandatory:** `run_pipeline` gains `tagger=None` (default None); with no tagger the tag stage does not tag (as today). The album-dir change must not alter the path for the existing (no-year, safe-name) tests. All existing tests must keep passing unchanged.
+- `MBTarget` gains `tracklist: tuple[str, ...] = ()` (defaulted; existing constructions unaffected).
+- `/music` is a host bind-mount configured via a `MUSIC_DIR` env var (default `./music`), mounted into the **worker** service only (the worker is what writes/reads the library). The real `MutagenTagger` is NOT unit-tested offline; covered by an opt-in test (`LYRA_LIVE_TESTS`) and the pure layout logic. Normal runs never touch real audio.
+- Every task ends with a commit.
+
+## Shared interfaces (defined by tasks below)
+
+```python
+# worker/lyra_worker/library.py (Task 1)
+def safe_name(s: str) -> str: ...                       # filesystem-safe path component
+def album_dir(dest_root: str, target: MBTarget) -> str: ...   # {dest_root}/{safe artist}/{safe album}[ (year)]
+
+# worker/lyra_worker/types.py (Task 2): MBTarget gains `tracklist: tuple[str, ...] = ()`
+
+# worker/lyra_worker/tagger.py (Task 2)
+class Tagger(Protocol):
+    def tag_album(self, album_dir: str, target: MBTarget) -> None: ...   # tag+rename the album's audio files
+
+# worker/lyra_worker/pipeline.py (Tasks 1-2): dest uses album_dir(); run_pipeline(..., tagger=None); tag stage calls tagger
+
+# worker/lyra_worker/_mutagen.py (Task 3)
+class MutagenTagger:   # real Tagger using mutagen (lazily imported)
+    def tag_album(self, album_dir, target) -> None: ...
+
+# worker/lyra_worker/registry.py (Task 4): build_tagger() -> Tagger
+```
+
+---
+
+### Task 1: Persistent /music volume + organized album directory
+
+**Files:**
+- Create: `worker/lyra_worker/library.py`
+- Test: `worker/tests/test_library.py`
+- Modify: `worker/lyra_worker/pipeline.py` (download dest uses `album_dir`)
+- Modify: `docker-compose.yml` (bind-mount `/music` on the worker)
+- Modify: `.env.example` (add `MUSIC_DIR`)
+
+**Interfaces:**
+- Consumes: `MBTarget`.
+- Produces: `safe_name(s) -> str` and `album_dir(dest_root, target) -> str`; the pipeline's download `dest` becomes `album_dir(dest_root, target)`; the worker mounts `${MUSIC_DIR}:/music`.
+
+- [ ] **Step 1: Write the failing test**
+
+`worker/tests/test_library.py`:
+```python
+from lyra_worker.library import album_dir, safe_name
+from lyra_worker.types import MBTarget
+
+
+def test_safe_name_replaces_illegal_chars():
+    assert safe_name("AC/DC") == "AC_DC"
+    assert safe_name('a:b*c?"') == "a_b_c__"
+    assert safe_name("  .Trailing. ") == "Trailing"
+    assert safe_name("") == "Unknown"
+
+
+def test_album_dir_with_year():
+    t = MBTarget(artist="John Mayer", album="Continuum", year=2006)
+    assert album_dir("/music", t) == "/music/John Mayer/Continuum (2006)"
+
+
+def test_album_dir_without_year():
+    t = MBTarget(artist="John Mayer", album="Continuum")
+    assert album_dir("/music", t) == "/music/John Mayer/Continuum"
+
+
+def test_album_dir_sanitizes():
+    t = MBTarget(artist="AC/DC", album="Back in Black", year=1980)
+    assert album_dir("/music", t) == "/music/AC_DC/Back in Black (1980)"
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run:
+```bash
+cd worker
+worker/.venv/bin/python -m pytest tests/test_library.py -v
+```
+Expected: FAIL — `ModuleNotFoundError: No module named 'lyra_worker.library'`.
+
+- [ ] **Step 3: Implement the library helpers**
+
+`worker/lyra_worker/library.py`:
+```python
+import re
+
+from lyra_worker.types import MBTarget
+
+_ILLEGAL = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
+
+
+def safe_name(s: str) -> str:
+    """A filesystem-safe path component (single segment, no separators)."""
+    cleaned = _ILLEGAL.sub("_", s).strip().strip(".").strip()
+    return cleaned or "Unknown"
+
+
+def album_dir(dest_root: str, target: MBTarget) -> str:
+    """`{dest_root}/{safe artist}/{safe album}[ (year)]`."""
+    album = safe_name(target.album)
+    if target.year:
+        album = f"{album} ({target.year})"
+    return f"{dest_root}/{safe_name(target.artist)}/{album}"
+```
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run:
+```bash
+cd worker
+worker/.venv/bin/python -m pytest tests/test_library.py -v
+```
+Expected: PASS — all four tests green.
+
+- [ ] **Step 5: Use album_dir for the download destination**
+
+In `worker/lyra_worker/pipeline.py`, add the import at the top:
+```python
+from lyra_worker.library import album_dir
+```
+In the download stage, replace the dest computation. Find:
+```python
+    dest = f"{dest_root}/{target.artist}/{target.album}"
+```
+Replace with:
+```python
+    dest = album_dir(dest_root, target)
+```
+(Nothing else in the pipeline changes in this task.)
+
+- [ ] **Step 6: Add the persistent /music bind-mount**
+
+In `.env.example`, add:
+```
+# Host directory for the downloaded music library (bind-mounted into the worker at /music)
+MUSIC_DIR=./music
+```
+In `docker-compose.yml`, add a `volumes:` entry to the `worker` service (alongside `build`, `restart`, `environment`, `depends_on`):
+```yaml
+    volumes:
+      - ${MUSIC_DIR:-./music}:/music
+```
+
+- [ ] **Step 7: Verify the compose config and the full worker suite**
+
+Run:
+```bash
+cd /home/jonathan/Projects/lyra
+docker compose config -q && echo "compose OK"
+cd worker
+export DATABASE_URL=postgresql://lyra:lyra@localhost:5432/lyra
+worker/.venv/bin/python -m pytest -q
+```
+Expected: `compose OK`; the full worker suite passes (the album_dir change doesn't alter paths for the existing no-year tests, so nothing regresses), output pristine.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add worker/lyra_worker/library.py worker/tests/test_library.py worker/lyra_worker/pipeline.py docker-compose.yml .env.example
+git commit -m "feat: organized album directory and persistent /music bind-mount"
+```
+
+---
+
+### Task 2: MBTarget.tracklist + Tagger seam + pipeline tag stage
+
+**Files:**
+- Modify: `worker/lyra_worker/types.py` (add `tracklist` to MBTarget)
+- Create: `worker/lyra_worker/tagger.py` (the `Tagger` Protocol)
+- Modify: `worker/lyra_worker/pipeline.py` (tag stage calls the tagger)
+- Test: `worker/tests/test_tag_stage.py`
+
+**Interfaces:**
+- Consumes: `MBTarget`.
+- Produces:
+  - `MBTarget.tracklist: tuple[str, ...] = ()`.
+  - `tagger.Tagger` Protocol: `tag_album(album_dir, target) -> None`.
+  - `run_pipeline(conn, job_id, adapters, resolver=None, tagger=None, ...)`: after the tag-stage completeness check passes, if `tagger is not None`, call `tagger.tag_album(dest, target)`. Tagger failures must NOT fail the job (log and continue) — a tagging error shouldn't discard a good download.
+
+- [ ] **Step 1: Add `tracklist` to MBTarget**
+
+In `worker/lyra_worker/types.py`, `MBTarget` gains a `tracklist` field (after `year`):
+```python
+@dataclass(frozen=True)
+class MBTarget:
+    artist: str
+    album: str
+    track_count: int | None = None
+    total_duration_s: int | None = None
+    year: int | None = None
+    tracklist: tuple[str, ...] = ()
+```
+
+- [ ] **Step 2: Add the Tagger Protocol**
+
+`worker/lyra_worker/tagger.py`:
+```python
+from typing import Protocol
+
+from lyra_worker.types import MBTarget
+
+
+class Tagger(Protocol):
+    def tag_album(self, album_dir: str, target: MBTarget) -> None:
+        """Tag the album's audio files with target's metadata and rename them."""
+        ...
+```
+
+- [ ] **Step 3: Write the failing tests**
+
+`worker/tests/test_tag_stage.py`:
+```python
+from lyra_worker.adapters.qobuz import QobuzAdapter
+from lyra_worker.claim import claim_next
+from lyra_worker.pipeline import run_pipeline
+from tests.conftest import insert_request
+from tests.test_qobuz_adapter import FakeQobuzClient
+
+
+class RecordingTagger:
+    def __init__(self, fail=False):
+        self.calls = []
+        self._fail = fail
+
+    def tag_album(self, album_dir, target):
+        self.calls.append((album_dir, target))
+        if self._fail:
+            raise RuntimeError("tagging blew up")
+
+
+def test_tagger_called_with_album_dir_and_target(conn):
+    tagger = RecordingTagger()
+    job_id = insert_request(conn, artist="John Mayer", album="Continuum")
+    claim_next(conn)
+    run_pipeline(conn, job_id, [QobuzAdapter(FakeQobuzClient())], tagger=tagger, dest_root="/tmp/lib")
+
+    with conn.cursor() as cur:
+        cur.execute('SELECT state FROM "Job" WHERE id = %s', (job_id,))
+        assert cur.fetchone()[0] == "imported"
+    assert len(tagger.calls) == 1
+    album_dir, target = tagger.calls[0]
+    assert album_dir == "/tmp/lib/John Mayer/Continuum"
+    assert target.album == "Continuum"
+
+
+def test_tagger_failure_does_not_fail_the_job(conn):
+    tagger = RecordingTagger(fail=True)
+    job_id = insert_request(conn, artist="John Mayer", album="Continuum")
+    claim_next(conn)
+    run_pipeline(conn, job_id, [QobuzAdapter(FakeQobuzClient())], tagger=tagger, dest_root="/tmp/lib")
+
+    with conn.cursor() as cur:
+        cur.execute('SELECT state FROM "Job" WHERE id = %s', (job_id,))
+        assert cur.fetchone()[0] == "imported"  # tagging error is logged, not fatal
+
+
+def test_no_tagger_still_imports(conn):
+    job_id = insert_request(conn, artist="John Mayer", album="Continuum")
+    claim_next(conn)
+    run_pipeline(conn, job_id, [QobuzAdapter(FakeQobuzClient())], dest_root="/tmp/lib")  # no tagger
+
+    with conn.cursor() as cur:
+        cur.execute('SELECT state FROM "Job" WHERE id = %s', (job_id,))
+        assert cur.fetchone()[0] == "imported"
+```
+
+- [ ] **Step 4: Run the tests to verify they fail**
+
+Run:
+```bash
+cd worker
+export DATABASE_URL=postgresql://lyra:lyra@localhost:5432/lyra
+worker/.venv/bin/python -m pytest tests/test_tag_stage.py -v
+```
+Expected: FAIL — `run_pipeline` does not accept a `tagger` argument (TypeError).
+
+- [ ] **Step 5: Add the tagger param and call it in the tag stage**
+
+In `worker/lyra_worker/pipeline.py`:
+
+(a) Add `tagger=None` to the signature (after `resolver`):
+```python
+def run_pipeline(
+    conn: psycopg.Connection,
+    job_id: str,
+    adapters: Sequence[SourceAdapter],
+    resolver=None,
+    tagger=None,
+    min_confidence: float = 0.7,
+    dest_root: str = "/music",
+) -> None:
+```
+
+(b) In the tag stage, after the completeness check passes (before the `# 6. import` block), add:
+```python
+    if tagger is not None:
+        try:
+            tagger.tag_album(dest, target)
+        except Exception as e:  # a tagging failure must not discard a good download
+            print(f"pipeline: tagging failed for job {job_id}: {e}", flush=True)
+```
+
+- [ ] **Step 6: Run the tests to verify they pass**
+
+Run:
+```bash
+cd worker
+export DATABASE_URL=postgresql://lyra:lyra@localhost:5432/lyra
+worker/.venv/bin/python -m pytest tests/test_tag_stage.py -v
+```
+Expected: PASS — all three tests green.
+
+- [ ] **Step 7: Run the full worker suite (backward compatibility)**
+
+Run:
+```bash
+cd worker
+export DATABASE_URL=postgresql://lyra:lyra@localhost:5432/lyra
+worker/.venv/bin/python -m pytest -q
+```
+Expected: PASS — every existing test still green (calls without `tagger` skip tagging), output pristine.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add worker/lyra_worker/types.py worker/lyra_worker/tagger.py worker/lyra_worker/pipeline.py worker/tests/test_tag_stage.py
+git commit -m "feat: Tagger seam and pipeline tag-stage integration"
+```
+
+---
+
+### Task 3: Real MutagenTagger + resolver tracklist + dependency + opt-in test
+
+**Files:**
+- Create: `worker/lyra_worker/_mutagen.py`
+- Modify: `worker/lyra_worker/_musicbrainz.py` (fill `tracklist`)
+- Create: `worker/tests/test_mutagen_live.py`
+- Modify: `worker/requirements.txt`
+
+**Interfaces:**
+- Consumes: `mutagen` (lazily imported), `MBTarget`, `safe_name`.
+- Produces: `MusicBrainzResolver.resolve` now fills `tracklist` (tuple of track titles, in order); `MutagenTagger.tag_album(album_dir, target)` tags each audio file (sorted) with artist/albumartist/album/date/tracknumber/title (title from `target.tracklist[i]` when available, else the filename stem) via mutagen easy mode, then renames it to `NN Title.ext`.
+
+- [ ] **Step 1: Add the dependency**
+
+Append to `worker/requirements.txt`:
+```
+mutagen>=1.47
+```
+Install into the venv: `worker/.venv/bin/pip install -r worker/requirements.txt`
+
+- [ ] **Step 2: Have the resolver fill the tracklist**
+
+In `worker/lyra_worker/_musicbrainz.py`, in the release-traversal block where `tracks` is collected, also build the ordered title list and pass it to `MBTarget`. After computing `track_count`/`total_duration_s`, add:
+```python
+                titles = tuple((t.get("recording") or {}).get("title", "") for t in tracks)
+```
+and add `tracklist=titles` to the returned `MBTarget(...)`. If no tracks were found, `tracklist` stays the default `()` — so also initialize `titles: tuple[str, ...] = ()` before the `if tracks:` block and set it inside, then pass `tracklist=titles`.
+
+- [ ] **Step 3: Implement the real tagger**
+
+The naming/numbering logic is a pure function (`plan_track_names`) so it can be unit-tested offline; only the mutagen tag-write is left to live validation.
+
+`worker/lyra_worker/_mutagen.py`:
+```python
+import os
+
+from lyra_worker.library import safe_name
+
+_AUDIO_EXT = {".flac", ".mp3", ".m4a", ".opus", ".ogg", ".aac", ".wav"}
+
+
+def plan_track_names(names: list[str], tracklist: tuple[str, ...]) -> list[tuple[str, str, str, int]]:
+    """Map audio filenames -> (old_name, new_name, title, track_number).
+
+    Files are sorted; titles come from `tracklist` by position when available,
+    else the filename stem. Pure — no filesystem or tag I/O.
+    """
+    plan: list[tuple[str, str, str, int]] = []
+    audio = sorted(n for n in names if os.path.splitext(n)[1].lower() in _AUDIO_EXT)
+    for i, name in enumerate(audio):
+        ext = os.path.splitext(name)[1].lower()
+        title = tracklist[i] if i < len(tracklist) else os.path.splitext(name)[0]
+        new_name = f"{i + 1:02d} {safe_name(title)}{ext}"
+        plan.append((name, new_name, title, i + 1))
+    return plan
+
+
+class MutagenTagger:
+    """Real Tagger using mutagen (lazily imported). The tag-write is not unit-tested
+    offline (needs real audio); the naming logic (`plan_track_names`) is."""
+
+    def tag_album(self, album_dir: str, target) -> None:
+        import mutagen
+
+        names = os.listdir(album_dir)
+        for old_name, new_name, title, number in plan_track_names(names, target.tracklist):
+            path = os.path.join(album_dir, old_name)
+            audio = mutagen.File(path, easy=True)
+            if audio is None:  # unreadable/unsupported file — leave it untouched
+                continue
+            audio["artist"] = target.artist
+            audio["albumartist"] = target.artist
+            audio["album"] = target.album
+            audio["title"] = title
+            audio["tracknumber"] = str(number)
+            if target.year:
+                audio["date"] = str(target.year)
+            audio.save()
+
+            new_path = os.path.join(album_dir, new_name)
+            if os.path.abspath(new_path) != os.path.abspath(path) and not os.path.exists(new_path):
+                os.rename(path, new_path)
+```
+
+- [ ] **Step 4: Write the offline naming test + the opt-in real-audio test**
+
+`worker/tests/test_mutagen.py` (offline — the pure naming logic):
+```python
+from lyra_worker._mutagen import plan_track_names
+
+
+def test_plan_uses_tracklist_titles_and_numbers():
+    names = ["02-b.flac", "01-a.flac"]  # unsorted on purpose
+    plan = plan_track_names(names, ("Alpha", "Beta"))
+    assert plan == [
+        ("01-a.flac", "01 Alpha.flac", "Alpha", 1),
+        ("02-b.flac", "02 Beta.flac", "Beta", 2),
+    ]
+
+
+def test_plan_falls_back_to_filename_stem_and_sanitizes():
+    plan = plan_track_names(["10 - AC_DC.mp3"], ())  # no tracklist
+    assert plan[0][1] == "01 10 - AC_DC.mp3"  # stem reused, renumbered, safe
+
+
+def test_plan_ignores_non_audio_files():
+    plan = plan_track_names(["cover.jpg", "song.opus", "notes.txt"], ())
+    assert [p[0] for p in plan] == ["song.opus"]
+```
+
+`worker/tests/test_mutagen_live.py` (opt-in — tags a real sample audio file the user supplies):
+```python
+import os
+import shutil
+
+import pytest
+
+pytestmark = pytest.mark.skipif(
+    not (os.environ.get("LYRA_LIVE_TESTS") and os.environ.get("LYRA_SAMPLE_AUDIO")),
+    reason="tags a real audio file; set LYRA_LIVE_TESTS=1 + LYRA_SAMPLE_AUDIO=/path/to/a.flac to run",
+)
+
+
+def test_tags_and_renames_a_real_file(tmp_path):
+    import mutagen
+
+    from lyra_worker._mutagen import MutagenTagger
+    from lyra_worker.types import MBTarget
+
+    ext = os.path.splitext(os.environ["LYRA_SAMPLE_AUDIO"])[1]
+    src = tmp_path / f"track1{ext}"
+    shutil.copy(os.environ["LYRA_SAMPLE_AUDIO"], src)
+
+    target = MBTarget(artist="John Mayer", album="Continuum", year=2006, tracklist=("Stop This Train",))
+    MutagenTagger().tag_album(str(tmp_path), target)
+
+    out = tmp_path / f"01 Stop This Train{ext}"
+    assert out.exists()
+    tagged = mutagen.File(str(out), easy=True)
+    assert tagged["artist"] == ["John Mayer"]
+    assert tagged["album"] == ["Continuum"]
+    assert tagged["title"] == ["Stop This Train"]
+    assert tagged["tracknumber"] == ["1"]
+```
+
+- [ ] **Step 5: Verify (offline) the imports, the naming tests, and that the live test is skipped**
+
+Run:
+```bash
+cd worker
+worker/.venv/bin/python -c "import sys; from lyra_worker._mutagen import MutagenTagger, plan_track_names; print('import ok; mutagen loaded:', 'mutagen' in sys.modules)"
+worker/.venv/bin/python -m pytest tests/test_mutagen.py tests/test_mutagen_live.py tests/test_library.py -v
+```
+Expected: prints `import ok; mutagen loaded: False` (mutagen imported lazily inside `tag_album`); `test_mutagen.py` (3 naming tests) passes; `test_mutagen_live.py` is **skipped**; library tests pass. Do NOT set the live env vars here.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add worker/lyra_worker/_mutagen.py worker/lyra_worker/_musicbrainz.py worker/tests/test_mutagen.py worker/tests/test_mutagen_live.py worker/requirements.txt
+git commit -m "feat: real mutagen tagger and MusicBrainz tracklist"
+```
+
+---
+
+### Task 4: Wire the tagger into the worker + end-to-end integration
+
+**Files:**
+- Modify: `worker/lyra_worker/registry.py` (add `build_tagger()`)
+- Modify: `worker/lyra_worker/main.py` (build + pass the tagger)
+- Test: `worker/tests/test_tag_pipeline.py`
+
+**Interfaces:**
+- Consumes: `MutagenTagger` (Task 3), `run_pipeline` (Task 2).
+- Produces: `registry.build_tagger() -> Tagger` returning a `MutagenTagger()`; `main.run_forever()` builds it once and passes it to `run_pipeline(conn, job_id, adapters, resolver=resolver, tagger=tagger)`.
+
+- [ ] **Step 1: Write the failing test**
+
+`worker/tests/test_tag_pipeline.py`:
+```python
+import os
+
+from lyra_worker.adapters.youtube import YouTubeAdapter
+from lyra_worker.claim import claim_next
+from lyra_worker.pipeline import run_pipeline
+from lyra_worker.registry import build_tagger
+from lyra_worker.types import MBTarget
+from tests.conftest import insert_request
+from tests.test_youtube_adapter import FakeYtClient
+
+
+def test_build_tagger_returns_a_tagger():
+    t = build_tagger()
+    assert hasattr(t, "tag_album")
+
+
+def test_download_dir_receives_files_and_tagger_runs(conn, tmp_path):
+    # A fake YouTube client that actually writes a file into dest, so a real MutagenTagger-shaped
+    # tagger has something to operate on. Here we use a recording tagger to assert it's invoked
+    # on the album directory the download wrote to.
+    written = {}
+
+    def fake_download(source_ref, dest, on_progress):
+        os.makedirs(dest, exist_ok=True)
+        open(os.path.join(dest, "track.opus"), "wb").close()
+        written["dir"] = dest
+        on_progress(1.0)
+        return {"track_count": 1, "path": dest}
+
+    client = FakeYtClient(results=[{"source_ref": "yt1", "title": "Continuum", "artist": "John Mayer", "track_count": 1}])
+    client.download = fake_download
+
+    class RecordingTagger:
+        def __init__(self):
+            self.seen = None
+
+        def tag_album(self, album_dir, target):
+            self.seen = album_dir
+
+    tagger = RecordingTagger()
+    job_id = insert_request(conn, artist="John Mayer", album="Continuum")
+    claim_next(conn)
+    run_pipeline(conn, job_id, [YouTubeAdapter(client)], tagger=tagger, dest_root=str(tmp_path))
+
+    with conn.cursor() as cur:
+        cur.execute('SELECT state FROM "Job" WHERE id = %s', (job_id,))
+        assert cur.fetchone()[0] == "imported"
+    assert tagger.seen == written["dir"]  # tagger ran on the exact directory the download wrote to
+    assert os.path.isdir(tagger.seen)
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run:
+```bash
+cd worker
+export DATABASE_URL=postgresql://lyra:lyra@localhost:5432/lyra
+worker/.venv/bin/python -m pytest tests/test_tag_pipeline.py -v
+```
+Expected: FAIL — `build_tagger` does not exist in `registry`.
+
+- [ ] **Step 3: Add build_tagger and wire it into main**
+
+In `worker/lyra_worker/registry.py`, add:
+```python
+from lyra_worker._mutagen import MutagenTagger
+from lyra_worker.tagger import Tagger
+
+
+def build_tagger() -> Tagger:
+    """The tagger that writes canonical metadata onto downloaded files."""
+    return MutagenTagger()
+```
+
+In `worker/lyra_worker/main.py`, update the import to include `build_tagger`, and in `run_forever()` build it once and pass it:
+```python
+    adapters = build_adapters(get_config(conn))
+    resolver = build_resolver()
+    tagger = build_tagger()
+    ...
+            run_pipeline(conn, job_id, adapters, resolver=resolver, tagger=tagger)
+```
+(Import line: `from lyra_worker.registry import build_adapters, build_resolver, build_tagger`.)
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run:
+```bash
+cd worker
+export DATABASE_URL=postgresql://lyra:lyra@localhost:5432/lyra
+worker/.venv/bin/python -m pytest tests/test_tag_pipeline.py -v
+```
+Expected: PASS — both tests green.
+
+- [ ] **Step 5: Run the full worker suite**
+
+Run:
+```bash
+cd worker
+export DATABASE_URL=postgresql://lyra:lyra@localhost:5432/lyra
+worker/.venv/bin/python -m pytest -q
+```
+Expected: PASS — every suite green, all live tests skipped, output pristine.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add worker/lyra_worker/registry.py worker/lyra_worker/main.py worker/tests/test_tag_pipeline.py
+git commit -m "feat: wire the mutagen tagger into the worker loop"
+```
+
+---
+
+## Notes: slice 1 complete
+
+With this plan, slice 1 (the acquisition engine) is functionally complete: a request is resolved against MusicBrainz, matched and ranked across Qobuz/Soulseek/YouTube, downloaded from the best source, verified for completeness against the canonical track count, tagged with canonical metadata, organized into `Artist/Album (Year)/## Title.ext`, and persisted to a host `/music` folder. The **live validation of `MutagenTagger`** (Task 3) is a user step: run `LYRA_LIVE_TESTS=1 pytest tests/test_mutagen_live.py`, and check real downloads land tagged and organized under `${MUSIC_DIR}`. Remaining hardening (deferred, non-blocking): worker in-loop reconnect, crash-resume/orphan-reaper for jobs dying mid-pipeline, `@@unique([jobId,sourceRef])` on Candidate, settings-form error handling, a config "clear field" path, and per-track file→MB matching by duration (currently files are matched to titles by sorted order). Slice 2 (library manager: monitoring, wanted lists, auto-grab) and slice 3 (discovery) are the next major phases, each with its own spec.
+```