From 566e6edbbdddcc92ddaa7242975513a9b50bbd31 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 8 Jun 2026 03:07:09 +0200
Subject: [PATCH 1/2] feat(albums,artists): browse endpoints over per-library
 album + artist surface (phase 4.d.0.4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds 4 read-only endpoints that close the loop on the album / artist
surface materialised by `apply::track` (phase 4.d.0.2) + the schema
shipped in `20260608120000_album_artist.sql` (phase 4.d.0.1):

  GET /api/v1/profiles/{p}/libraries/{l}/albums
  GET /api/v1/profiles/{p}/libraries/{l}/albums/{id}/tracks
  GET /api/v1/profiles/{p}/libraries/{l}/artists
  GET /api/v1/profiles/{p}/libraries/{l}/artists/{id}/tracks

Pattern lifts the 2-query ownership-check + fetch idiom from
`db::playlist_track::fetch_for_owner` so 404 (library / album /
artist missing or foreign-owned) stays distinct from 200 [] (owned
but empty). The race window is benign — every parent cascades on
DELETE so a row vanishing between the two queries collapses to the
empty-list answer.

Album list joins `artist` once to surface `album_artist_name` (avoids
N artist lookups client-side). Compilation rows project null +
is_compilation=true. Drill-down ORDER BY rides the indexes the
schema migration planted: album → (disc_number, track_number, id),
artist → (disc_number, track_number, id) via track_artist join.

Writes deliberately not exposed — album / artist rows come from the
apply pipeline only.

TrackResponse gains `album_id` so the artist drill-down can deep-link
contributed tracks to their album page without N extra round-trips.
Existing `/tracks` collection still NULL-projects the column (its
SELECT lives in waveflow-core); follow-up PR bumps core.

Test coverage: empty → 200 [], ordering by updated_at DESC, tied
updated_at → id ASC tiebreak (guards the apply-pipeline-batch
invariant), compilation NULL projection, multi-artist tracks surface
under every contributor, full cross-tenant battery (foreign user,
foreign profile, wrong library_id pivot). OpenAPI snapshot guards
the 4 new paths.

Doc bullet added to server CLAUDE.md.

Signed-off-by: InstaZDLL <github.105mh@8shield.net>
---
 CLAUDE.md          |   1 +
 src/api/albums.rs  | 173 ++++++++++++++++
 src/api/artists.rs | 145 ++++++++++++++
 src/api/mod.rs     |  14 +-
 src/api/tracks.rs  |  12 ++
 src/db.rs          | 307 +++++++++++++++++++++++++++++
 tests/albums.rs    | 479 +++++++++++++++++++++++++++++++++++++++++++++
 tests/artists.rs   | 413 ++++++++++++++++++++++++++++++++++++++
 tests/openapi.rs   |  23 +++
 9 files changed, 1564 insertions(+), 3 deletions(-)
 create mode 100644 src/api/albums.rs
 create mode 100644 src/api/artists.rs
 create mode 100644 tests/albums.rs
 create mode 100644 tests/artists.rs

diff --git a/CLAUDE.md b/CLAUDE.md
index 90213c5..0d9e37c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -43,6 +43,7 @@ CI runs the full suite only on Linux (service container); the Windows leg is a c
 - **Auth: JWT-only (Phase 1.d.2).** `middleware::authenticate` requires a Bearer JWT signed by the upstream Better Auth issuer. The middleware verifies the token via [`AppState::jwt_verifier`], then `db::users::find_or_provision_by_external_id(state.db, &sub, now_ms)` lazy-onboards the user on first request — a valid signature is the authoritative onboarding signal, so no separate `POST /api/v1/users` exists. Boot requires the full `WAVEFLOW_JWT_*` triple (`_JWKS_URL` / `_ISSUER` / `_AUDIENCE`); the legacy `X-User-Id` dev shim retired alongside `WAVEFLOW_DEV_AUTH`.
 - **Streaming (Phase 1.e).** Two endpoints: `POST /api/v1/profiles/{p}/libraries/{l}/tracks/{t}/stream-url` (JWT-authed) verifies tenant ownership and signs a short-lived (≤ 60 s) URL via [`stream_token::mint`]; `GET /api/v1/stream/{token}` is mounted OUTSIDE the JWT layer because browsers can't attach a Bearer to `<audio src>` — the HMAC in the token IS the auth. The stream handler canonicalises `<music_root>/<file_path>` and refuses anything resolving outside `WAVEFLOW_MUSIC_ROOT` (path-traversal guard via `std::fs::canonicalize` + prefix check). Range requests handled in-process: `Accept-Ranges: bytes`, 206 + `Content-Range` on partial, 416 on unsatisfiable. Both endpoints answer 503 when streaming is disabled at boot (`WAVEFLOW_MUSIC_ROOT` + `WAVEFLOW_STREAM_SECRET` unset). Until 1.f's sync ships, files must be placed manually under the music root.
 - **Track sync (Phase 4.d.0.2).** Adds `"track"` to the apply pipeline alongside `"playlist"` / `"library"` (all three profile-scoped, so they share the dispatcher's `profile_canonical_id` gate). Wire shape: `entity_id = file_path` — the per-library natural identity (`UNIQUE (library_id, file_path)` from `20260530000003_track.sql:64`). The BLAKE3 hash rides as a payload field (`file_hash`), not as `entity_id`: using the hash as identity would break the tag-editor re-emit flow because lofty rewrites embedded metadata frames on save (file_hash changes, file_path doesn't) — the upsert would miss its arbiter, fall through to INSERT, and trip the pre-existing `(library_id, file_path)` UNIQUE. The cross-device-content identity from `20260604000000_apply_pipeline.sql:26-33` still lives in the `track.file_hash` column for liked_track / rating joins; it just isn't the row identity for the `track` entity itself. `payload.library_canonical_id` carries the tenant scope. INSERT payload also packs the full track metadata + the album/artist plumbing: `album_title?`, `album_artist_name?` (None → compilation), `is_compilation?`, `artists?: [String, ...]` (the desktop's `";"`-split list — position derives from array index). Empty-string `album_title` / `album_artist_name` are rejected at the apply boundary as InvalidPayload (400-family) so they never trip the `length(...) > 0` CHECK constraints on `album` / `artist` (which would surface as 500). The handler chain: resolve library_id from canonical id (Skipped if not yet materialised), upsert every contributor artist, resolve album_artist_id (dedup against contributors), upsert album, upsert track on `(library_id, file_path)`, then DELETE + single UNNEST INSERT for the `track_artist` link rows. SET ops are intentionally Unknown: the desktop's tag-editor save rewrites the audio file and re-emits a full INSERT — the upsert handles re-emit as a merge (every scalar column overwrites on conflict, including `file_hash`). DELETE is keyed on `(library_id, file_path)` and cascades into `track_artist` via the schema FK. Helpers in `db::track_sync` (`upsert_artist`, `upsert_album`, `upsert_track`, `replace_track_artists`, `lookup_library_id`); apply orchestration in `apply.rs::track`.
+- **Album + artist browse (Phase 4.d.0.4).** Four read-only endpoints expose the per-library album / artist surface materialised by the apply pipeline: `GET /api/v1/profiles/{p}/libraries/{l}/albums` + `/artists` list every row under the tenant chain `library → profile → user`, most-recently-updated first (rides the `album_library_updated_idx` / `artist_library_updated_idx` planted in `20260608120000_album_artist.sql:217-221`; `id ASC` tie-break on equal `updated_at` so the order is deterministic when a batch upsert stamps several rows at the same millisecond). The album list joins `artist` once to surface `album_artist_name` so the web client doesn't fan out N artist lookups (compilation rows project `null` `album_artist_id` + `album_artist_name` + `is_compilation = true`). Drill-down: `/albums/{id}/tracks` orders by `(disc_number, track_number, id)` (sleeve order, rides `track_album_idx`); `/artists/{id}/tracks` joins through `track_artist` so a multi-artist track surfaces under every contributor (`DISTINCT` is defensive since the PK already guarantees no dupes — keeps a future schema relax safe). All four use the **2-query ownership-check + fetch** pattern from [`db::playlist_track::fetch_for_owner`](src/db.rs): an ownership SELECT first to distinguish 404 (library / album / artist missing or foreign-owned) from 200 `[]` (owned but empty); the race window between the two is benign because every parent carries `ON DELETE CASCADE` (the only way a row can vanish mid-request is parent deletion, which makes `[]` the correct answer). Writes are NOT exposed — album / artist rows materialise from `apply::track` (4.d.0.2). 404-blur convention matches every other tenant-scoped endpoint. Helpers in [`db::album`](src/db.rs) + [`db::artist`](src/db.rs); handlers in [`api/albums.rs`](src/api/albums.rs) + [`api/artists.rs`](src/api/artists.rs).
 - **Album + artist schema (Phase 4.d.0.1).** `album`, `artist`, `track_artist` tables ship in [`migrations/20260608120000_album_artist.sql`](migrations/20260608120000_album_artist.sql), plus a nullable `track.album_id` FK. Per-library scope (matches `track.library_id`) — the same album in two libraries = two rows, deleting a library reclaims its album + artist + track_artist rows in one cascade. Natural keys: `album` is `(library_id, canonical_title, album_artist_id)` with `UNIQUE NULLS NOT DISTINCT` (PG15+; we target PG17) so two compilation rows with NULL `album_artist_id` collapse to one — without it the apply-time upsert would have to special-case the IS NULL match. `artist` is `(library_id, name)`. `track_artist` PK is `(track_id, artist_id)` with a `position` column preserving the multi-artist ordering the desktop ships (semicolon-split per WaveFlow CLAUDE.md "Multi-artist queries"). FK posture: `track_artist` cascades both ways (track or artist gone → row gone), `album.album_artist_id` SET NULL on artist delete (don't lose the album row), `track.album_id` SET NULL on album delete (don't lose the audio file row). **Cross-library scope is enforced at the schema** via composite FKs — every entity-to-entity link carries `library_id` in BOTH columns of the FK with the parent's `UNIQUE (id, library_id)` as target, so an attempt to set `album.album_artist_id` to an artist in a different library (or `track.album_id` to a foreign album, or `track_artist` to a cross-library pair) is rejected at INSERT/UPDATE time. `track_artist` carries a denormalised `library_id` for this; the apply pipeline (4.d.0.2) derives it from `track.library_id` at upsert. `ON DELETE SET NULL (col)` (PG15+ column-level form) drops only the FK link when the parent is deleted, leaving `library_id` intact. Schema-only here — the apply pipeline upsert lands in 4.d.0.2 and the read endpoints in 4.d.0.4.
 - **playlist_track materialisation (Phase 1.j.a).** Apply pipeline writes `playlist + field: "tracks"` ops into a dedicated `playlist_track` table that mirrors the desktop SQLite shape at [`profile/20260411120000_initial.sql:236`](https://github.com/InstaZDLL/WaveFlow/blob/main/src-tauri/migrations/profile/20260411120000_initial.sql) — `(playlist_id, track_id)` PK + position index, BIGINT epoch-millis for `added_at`. The `track_id` column is the source desktop's local-i64 id (no FK because the server has no `track` table yet — Phase 1.k territory); per-row snapshot columns (`snapshot_title`, `snapshot_artist`, `snapshot_duration_ms`) carry the displayable values cross-device so the public share preview can render the tracks. Wire shape:`payload.track_ids: [N, …]` for insert + delete (required); optional `payload.snapshots: { "<id_str>": { title, artist?, duration_ms? } }` for the 1.j.b wire bump that desktops gain in a follow-up release. Pre-1.j.b desktops emit ops without `snapshots` — rows land with NULL snapshot fields and stay invisible in the public preview (`fetch_for_share` filters `snapshot_title IS NOT NULL`). `set tracks` carries `{ track_id, position }` for single-row reorder. `insert_tracks` UPSERTs with `COALESCE`-merged snapshots so a future re-emit with richer metadata enriches the existing row instead of clobbering it. Parent-playlist lookup misses surface as `Skipped` (not `Applied`) so the durable log keeps the op for replay once the playlist insert lands. **Owner read surface (Phase 1.j.c)**: `GET /api/v1/profiles/{profile_id}/playlists/{id}/tracks` returns every row in `(position ASC, track_id ASC)` order — snapshot fields nullable in the response because the owner is allowed to see pre-1.j.b rows (the public-preview snapshot filter does NOT apply here). 404 blurs "no such playlist" / "wrong profile" / "wrong user" with the same shape, same no-existence-leak rationale as `get_playlist`. Two round-trips on purpose (`db::playlist_track::fetch_for_owner`) — a single CTE-joined SELECT conflates "not owned" with "owned but empty" in the result set, and we need that distinction at the HTTP boundary.
 - **Artwork background scanner (Phase 1.i.1).** Tokio task spawned at boot when both the artwork backend AND the scanner are configured (`WAVEFLOW_ARTWORK_SCANNER_DISABLED` to opt out; defaults: 5-minute cadence, 50 parents per cycle). Lives in [`src/artwork_jobs.rs`](src/artwork_jobs.rs); same shape as the sync compaction loop (`SyncHub::spawn`'s nightly task). Each cycle calls `db::artwork::list_partial_parents` (`COUNT(metadata_artwork_variant) < EXPECTED_VARIANT_COUNT`, oldest-first), pulls the source bytes from object_store, re-runs the resize pipeline, and inserts only the variants still missing — race-safe via `ON CONFLICT (parent_hash, variant) DO NOTHING`, so a concurrent upload-side repair (or a peer scanner instance in a multi-replica deploy) collapses cleanly. Per-parent failures are logged + skipped; the cycle only errors on a top-level DB failure. **We deliberately picked a tokio polling loop over `apalis` for 1.i.1** — the workload is "periodic catch-up" rather than "queue-driven retries with priorities", and the surrounding infra already has a compaction loop to generalise from. `apalis` lands when a job type genuinely needs persistent queues + priorities (e.g. RFC-004 community moderation).
diff --git a/src/api/albums.rs b/src/api/albums.rs
new file mode 100644
index 0000000..a0cef1f
--- /dev/null
+++ b/src/api/albums.rs
@@ -0,0 +1,173 @@
+//! `/api/v1/profiles/{profile_id}/libraries/{library_id}/albums*` —
+//! tenant-scoped read surface over the `album` table (Phase 4.d.0.4).
+//!
+//! Same nested pattern as `tracks.rs`: every handler reads [`UserId`]
+//! from the request extension, threads the path's `profile_id` +
+//! `library_id` through, and calls into [`crate::db::album`]. The
+//! repository SQL walks `album → library → profile → user` inline so
+//! requests targeting a foreign profile / foreign library / foreign
+//! album short-circuit at the storage layer.
+//!
+//! Writes are NOT exposed here. Album rows materialise from the sync
+//! apply pipeline (`apply::track`, phase 4.d.0.2) — they're derived
+//! from the desktop's tag metadata, not user-created on the server.
+//! Same rationale as the artist endpoints in [`super::artists`].
+//!
+//! 404 (vs 403) on missing / foreign-owned rows is deliberate — same
+//! no-existence-leak rationale as every other tenant-scoped endpoint.
+
+use axum::{
+    extract::{Extension, Path, State},
+    http::StatusCode,
+    response::IntoResponse,
+    Json,
+};
+use serde::Serialize;
+use utoipa::ToSchema;
+use utoipa_axum::{router::OpenApiRouter, routes};
+
+use crate::{db, middleware::UserId, AppState};
+
+use super::tracks::TrackResponse;
+
+/// Wire-format album row. Surfaces the `album_artist_name` joined
+/// from `artist` so the web client's album-grid doesn't have to
+/// resolve N artist names one-by-one. `album_artist_id` rides
+/// alongside so the UI can deep-link straight into the artist
+/// drill-down without a name → id lookup.
+///
+/// `album_artist_*` are `None` for compilations (the schema's
+/// `NULLS NOT DISTINCT` natural key collapses NULL `album_artist_id`
+/// to a single row per `(library, title)`); the UI renders the
+/// "Various Artists" label client-side based on `is_compilation`.
+#[derive(Debug, Serialize, ToSchema)]
+pub struct AlbumResponse {
+    pub id: i64,
+    pub canonical_title: String,
+    pub album_artist_id: Option<i64>,
+    pub album_artist_name: Option<String>,
+    pub year: Option<i64>,
+    /// BLAKE3 hex of the album cover in the shared metadata cache.
+    /// `None` until the server-side cover-extraction pipeline ships.
+    pub cover_hash: Option<String>,
+    pub is_compilation: bool,
+    pub created_at: i64,
+    pub updated_at: i64,
+}
+
+impl From<db::album::AlbumRow> for AlbumResponse {
+    fn from(row: db::album::AlbumRow) -> Self {
+        Self {
+            id: row.id,
+            canonical_title: row.canonical_title,
+            album_artist_id: row.album_artist_id,
+            album_artist_name: row.album_artist_name,
+            year: row.year,
+            cover_hash: row.cover_hash,
+            is_compilation: row.is_compilation,
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+        }
+    }
+}
+
+pub fn router(state: AppState) -> OpenApiRouter {
+    OpenApiRouter::new()
+        .routes(routes!(list_albums))
+        .routes(routes!(list_album_tracks))
+        .with_state(state)
+}
+
+/// List every album under `(profile_id, library_id)` owned by the
+/// calling user, most-recently-updated first. 404 covers "no such
+/// library" / "library belongs to a foreign profile" / "foreign user"
+/// — same no-leak blur as `get_library`. An owned-but-empty library
+/// returns `200 []`.
+#[utoipa::path(
+    get,
+    path = "/api/v1/profiles/{profile_id}/libraries/{library_id}/albums",
+    tag = "albums",
+    params(
+        ("authorization" = String, Header, description = "Bearer JWT issued by Better Auth"),
+        ("profile_id" = i64, Path, description = "Owning profile id"),
+        ("library_id" = i64, Path, description = "Owning library id"),
+    ),
+    responses(
+        (status = 200, description = "Albums under the library, most-recently-updated first", body = Vec<AlbumResponse>),
+        (status = 401, description = "Missing or invalid bearer token"),
+        (status = 404, description = "Library / profile not owned by the calling user"),
+        (status = 500, description = "Database or internal failure (body is a plain-text reason)"),
+    ),
+)]
+async fn list_albums(
+    State(state): State<AppState>,
+    Extension(UserId(user_id)): Extension<UserId>,
+    Path((profile_id, library_id)): Path<(i64, i64)>,
+) -> impl IntoResponse {
+    match db::album::list_for_library(&state.db, library_id, profile_id, user_id).await {
+        Ok(Some(rows)) => {
+            let body: Vec<AlbumResponse> = rows.into_iter().map(Into::into).collect();
+            (StatusCode::OK, Json(body)).into_response()
+        }
+        Ok(None) => (StatusCode::NOT_FOUND, "library not found").into_response(),
+        Err(err) => {
+            tracing::error!(
+                error = %err,
+                user_id,
+                profile_id,
+                library_id,
+                "list albums failed"
+            );
+            (StatusCode::INTERNAL_SERVER_ERROR, "list failed").into_response()
+        }
+    }
+}
+
+/// Drill-down: list every track linked to `album_id` under
+/// `(profile_id, library_id)`, ordered `(disc_number, track_number,
+/// id)` so the standard "Side A → Side B" sleeve order falls out
+/// naturally. 404 blurs every non-owned case. An owned album with
+/// no remaining tracks (every linked track was deleted; the album
+/// row outlives its tracks via `ON DELETE SET NULL`) returns
+/// `200 []`.
+#[utoipa::path(
+    get,
+    path = "/api/v1/profiles/{profile_id}/libraries/{library_id}/albums/{id}/tracks",
+    tag = "albums",
+    params(
+        ("authorization" = String, Header, description = "Bearer JWT issued by Better Auth"),
+        ("profile_id" = i64, Path, description = "Owning profile id"),
+        ("library_id" = i64, Path, description = "Owning library id"),
+        ("id" = i64, Path, description = "Album id"),
+    ),
+    responses(
+        (status = 200, description = "Tracks under the album, in sleeve order (may be empty)", body = Vec<TrackResponse>),
+        (status = 401, description = "Missing or invalid bearer token"),
+        (status = 404, description = "No album with that id under the (library, profile) owned by the calling user"),
+        (status = 500, description = "Database or internal failure (body is a plain-text reason)"),
+    ),
+)]
+async fn list_album_tracks(
+    State(state): State<AppState>,
+    Extension(UserId(user_id)): Extension<UserId>,
+    Path((profile_id, library_id, id)): Path<(i64, i64, i64)>,
+) -> impl IntoResponse {
+    match db::album::list_tracks_for_album(&state.db, id, library_id, profile_id, user_id).await {
+        Ok(Some(rows)) => {
+            let body: Vec<TrackResponse> = rows.into_iter().map(Into::into).collect();
+            (StatusCode::OK, Json(body)).into_response()
+        }
+        Ok(None) => (StatusCode::NOT_FOUND, "album not found").into_response(),
+        Err(err) => {
+            tracing::error!(
+                error = %err,
+                id,
+                user_id,
+                profile_id,
+                library_id,
+                "list album tracks failed"
+            );
+            (StatusCode::INTERNAL_SERVER_ERROR, "list tracks failed").into_response()
+        }
+    }
+}
diff --git a/src/api/artists.rs b/src/api/artists.rs
new file mode 100644
index 0000000..04b3964
--- /dev/null
+++ b/src/api/artists.rs
@@ -0,0 +1,145 @@
+//! `/api/v1/profiles/{profile_id}/libraries/{library_id}/artists*` —
+//! tenant-scoped read surface over the `artist` table (Phase 4.d.0.4).
+//!
+//! Same shape as [`super::albums`], one table over. Writes are not
+//! exposed — artist rows materialise from the sync apply pipeline
+//! (`apply::track`), not from a user-facing CRUD form.
+//!
+//! The drill-down "tracks contributed by this artist" surfaces every
+//! row from `track_artist` (multi-artist tracks appear under each
+//! contributor), `ORDER BY (disc_number, track_number, id)` to match
+//! the album drill-down's sleeve-order feel.
+
+use axum::{
+    extract::{Extension, Path, State},
+    http::StatusCode,
+    response::IntoResponse,
+    Json,
+};
+use serde::Serialize;
+use utoipa::ToSchema;
+use utoipa_axum::{router::OpenApiRouter, routes};
+
+use crate::{db, middleware::UserId, AppState};
+
+use super::tracks::TrackResponse;
+
+/// Wire-format artist row. `picture_hash` rides through the same
+/// shared metadata cache as `album.cover_hash` / `playlist.cover_hash`
+/// — `None` until the server-side artist-picture pipeline ships.
+#[derive(Debug, Serialize, ToSchema)]
+pub struct ArtistResponse {
+    pub id: i64,
+    pub name: String,
+    pub picture_hash: Option<String>,
+    pub created_at: i64,
+    pub updated_at: i64,
+}
+
+impl From<db::artist::ArtistRow> for ArtistResponse {
+    fn from(row: db::artist::ArtistRow) -> Self {
+        Self {
+            id: row.id,
+            name: row.name,
+            picture_hash: row.picture_hash,
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+        }
+    }
+}
+
+pub fn router(state: AppState) -> OpenApiRouter {
+    OpenApiRouter::new()
+        .routes(routes!(list_artists))
+        .routes(routes!(list_artist_tracks))
+        .with_state(state)
+}
+
+/// List every artist under `(profile_id, library_id)` owned by the
+/// calling user, most-recently-updated first. 404 covers every
+/// non-owned case; an owned-but-empty library returns `200 []`.
+#[utoipa::path(
+    get,
+    path = "/api/v1/profiles/{profile_id}/libraries/{library_id}/artists",
+    tag = "artists",
+    params(
+        ("authorization" = String, Header, description = "Bearer JWT issued by Better Auth"),
+        ("profile_id" = i64, Path, description = "Owning profile id"),
+        ("library_id" = i64, Path, description = "Owning library id"),
+    ),
+    responses(
+        (status = 200, description = "Artists under the library, most-recently-updated first", body = Vec<ArtistResponse>),
+        (status = 401, description = "Missing or invalid bearer token"),
+        (status = 404, description = "Library / profile not owned by the calling user"),
+        (status = 500, description = "Database or internal failure (body is a plain-text reason)"),
+    ),
+)]
+async fn list_artists(
+    State(state): State<AppState>,
+    Extension(UserId(user_id)): Extension<UserId>,
+    Path((profile_id, library_id)): Path<(i64, i64)>,
+) -> impl IntoResponse {
+    match db::artist::list_for_library(&state.db, library_id, profile_id, user_id).await {
+        Ok(Some(rows)) => {
+            let body: Vec<ArtistResponse> = rows.into_iter().map(Into::into).collect();
+            (StatusCode::OK, Json(body)).into_response()
+        }
+        Ok(None) => (StatusCode::NOT_FOUND, "library not found").into_response(),
+        Err(err) => {
+            tracing::error!(
+                error = %err,
+                user_id,
+                profile_id,
+                library_id,
+                "list artists failed"
+            );
+            (StatusCode::INTERNAL_SERVER_ERROR, "list failed").into_response()
+        }
+    }
+}
+
+/// Drill-down: every track contributed by `artist_id` under
+/// `(profile_id, library_id)`. Multi-artist tracks appear under every
+/// contributor — `track_artist` is the source of truth, scoped by
+/// `library_id` so the result never crosses a tenant boundary.
+#[utoipa::path(
+    get,
+    path = "/api/v1/profiles/{profile_id}/libraries/{library_id}/artists/{id}/tracks",
+    tag = "artists",
+    params(
+        ("authorization" = String, Header, description = "Bearer JWT issued by Better Auth"),
+        ("profile_id" = i64, Path, description = "Owning profile id"),
+        ("library_id" = i64, Path, description = "Owning library id"),
+        ("id" = i64, Path, description = "Artist id"),
+    ),
+    responses(
+        (status = 200, description = "Tracks contributed by the artist (may be empty)", body = Vec<TrackResponse>),
+        (status = 401, description = "Missing or invalid bearer token"),
+        (status = 404, description = "No artist with that id under the (library, profile) owned by the calling user"),
+        (status = 500, description = "Database or internal failure (body is a plain-text reason)"),
+    ),
+)]
+async fn list_artist_tracks(
+    State(state): State<AppState>,
+    Extension(UserId(user_id)): Extension<UserId>,
+    Path((profile_id, library_id, id)): Path<(i64, i64, i64)>,
+) -> impl IntoResponse {
+    match db::artist::list_tracks_for_artist(&state.db, id, library_id, profile_id, user_id).await {
+        Ok(Some(rows)) => {
+            let body: Vec<TrackResponse> = rows.into_iter().map(Into::into).collect();
+            (StatusCode::OK, Json(body)).into_response()
+        }
+        Ok(None) => (StatusCode::NOT_FOUND, "artist not found").into_response(),
+        Err(err) => {
+            tracing::error!(
+                error = %err,
+                id,
+                user_id,
+                profile_id,
+                library_id,
+                "list artist tracks failed"
+            );
+            (StatusCode::INTERNAL_SERVER_ERROR, "list tracks failed").into_response()
+        }
+    }
+}
diff --git a/src/api/mod.rs b/src/api/mod.rs
index dcbeddd..667e65e 100644
--- a/src/api/mod.rs
+++ b/src/api/mod.rs
@@ -5,9 +5,11 @@
 //! readiness, `profiles.rs` covers tenant-scoped profile CRUD,
 //! `libraries.rs` covers tenant-scoped library CRUD nested under a
 //! profile, `tracks.rs` covers tenant-scoped track CRUD nested under
-//! a library, `playlists.rs` covers tenant-scoped playlist CRUD
-//! nested under a profile. Future modules will cover `sync`, `stream`
-//! (per RFC-001 §6 / §7).
+//! a library, `albums.rs` + `artists.rs` cover the read-only browse
+//! surface materialised by the sync apply pipeline (phase 4.d.0.4),
+//! `playlists.rs` covers tenant-scoped playlist CRUD nested under a
+//! profile. Future modules will cover `sync`, `stream` (per RFC-001
+//! §6 / §7).
 //!
 //! Versioning policy: every resource module mounts under `/api/v1/`
 //! (except `/health` and `/ready`, which are unversioned by
@@ -29,6 +31,8 @@ use utoipa_axum::router::OpenApiRouter;
 
 use crate::{middleware as auth_middleware, AppState};
 
+mod albums;
+mod artists;
 mod artwork;
 mod health;
 mod libraries;
@@ -55,6 +59,8 @@ pub fn router(state: AppState) -> OpenApiRouter {
     let profiles_router = profiles::router(state.clone()).layer(auth_layer.clone());
     let libraries_router = libraries::router(state.clone()).layer(auth_layer.clone());
     let tracks_router = tracks::router(state.clone()).layer(auth_layer.clone());
+    let albums_router = albums::router(state.clone()).layer(auth_layer.clone());
+    let artists_router = artists::router(state.clone()).layer(auth_layer.clone());
     let playlists_router = playlists::router(state.clone()).layer(auth_layer.clone());
     let sync_router = sync::router(state.clone()).layer(auth_layer.clone());
     // Mint + revoke stay JWT-authed (verify tenant ownership before
@@ -85,6 +91,8 @@ pub fn router(state: AppState) -> OpenApiRouter {
         .merge(profiles_router)
         .merge(libraries_router)
         .merge(tracks_router)
+        .merge(albums_router)
+        .merge(artists_router)
         .merge(playlists_router)
         .merge(sync_router)
         .merge(share_mint_router)
diff --git a/src/api/tracks.rs b/src/api/tracks.rs
index 2ada64a..42294ce 100644
--- a/src/api/tracks.rs
+++ b/src/api/tracks.rs
@@ -46,6 +46,17 @@ use crate::{middleware::UserId, AppState};
 pub struct TrackResponse {
     pub id: i64,
     pub library_id: i64,
+    /// FK into `album`. NULL for free-form tracks the apply pipeline
+    /// couldn't group (no album metadata in the source tag). Populated
+    /// from `t.album_id` by every endpoint that returns this struct.
+    /// The Phase 4.d.0.4 drill-down (`/artists/{id}/tracks`) relies on
+    /// this so a contributed track can deep-link to its album page
+    /// without an extra `/tracks/{id}` round-trip per row. The legacy
+    /// `/tracks` collection currently still NULL-projects the column
+    /// (its SELECT lives in waveflow-core and predates the album
+    /// table); a follow-up bumps core to project the real value
+    /// everywhere.
+    pub album_id: Option<i64>,
     pub title: String,
     pub duration_ms: i64,
     pub track_number: Option<i64>,
@@ -70,6 +81,7 @@ impl From<TrackRow> for TrackResponse {
         Self {
             id: t.id,
             library_id: t.library_id,
+            album_id: t.album_id,
             title: t.title,
             duration_ms: t.duration_ms,
             track_number: t.track_number,
diff --git a/src/db.rs b/src/db.rs
index 892a939..aeb8437 100644
--- a/src/db.rs
+++ b/src/db.rs
@@ -938,6 +938,313 @@ pub mod track_sync {
     }
 }
 
+/// Album browse helpers (Phase 4.d.0.4). Reads against the `album`
+/// table for the `GET /api/v1/profiles/{p}/libraries/{l}/albums`
+/// surface plus the per-album drill-down. Writes still go through
+/// `track_sync::upsert_album` from the apply pipeline — this module
+/// is read-only.
+///
+/// Same 2-query ownership-check + fetch shape as
+/// [`playlist_track::fetch_for_owner`]: ownership SELECT first to
+/// distinguish 404 ("library not owned" / "album not owned") from
+/// 200 `[]` ("owned but empty"), then the bulk row fetch. The race
+/// window between the two is benign because every parent (library →
+/// profile) carries `ON DELETE CASCADE` — the only way a row can
+/// vanish between the two queries is parent-tenant deletion, which
+/// makes `[]` the correct answer (same shape a brand-new empty
+/// library returns).
+pub mod album {
+    use sqlx::PgPool;
+    use waveflow_core::domain::track::TrackRow;
+
+    /// Wire-shaped album row. Joins `artist` once to surface the
+    /// `album_artist_name` so the album-grid UI on the web doesn't
+    /// have to fan out N artist lookups. `album_artist_name` is
+    /// `None` for compilations (the schema's `NULLS NOT DISTINCT`
+    /// collapse keeps one row per `(library, title)` with NULL
+    /// `album_artist_id`).
+    #[derive(Debug, Clone, PartialEq, Eq, sqlx::FromRow)]
+    pub struct AlbumRow {
+        pub id: i64,
+        pub canonical_title: String,
+        pub album_artist_id: Option<i64>,
+        pub album_artist_name: Option<String>,
+        pub year: Option<i64>,
+        pub cover_hash: Option<String>,
+        pub is_compilation: bool,
+        pub created_at: i64,
+        pub updated_at: i64,
+    }
+
+    /// List every album under `(library_id, profile_id, user_id)`,
+    /// most-recently-updated first. `Ok(None)` covers "no such
+    /// library", "library belongs to another profile", and "profile
+    /// belongs to another user" — the handler blurs the three into
+    /// a single 404. `Ok(Some(vec![]))` is "owned but empty" and
+    /// renders as `[]`. The ORDER BY rides
+    /// `album_library_updated_idx (library_id, updated_at DESC)`
+    /// planted in `20260608120000_album_artist.sql:217-218`.
+    ///
+    /// `id ASC` is the tie-breaker on equal `updated_at` so the
+    /// order is deterministic across pages even when a batch
+    /// upsert (the apply pipeline runs a whole sync round in one
+    /// transaction) stamps several rows with the same epoch
+    /// millisecond — without it, list pagination would shuffle on
+    /// each request.
+    pub async fn list_for_library(
+        pool: &PgPool,
+        library_id: i64,
+        profile_id: i64,
+        user_id: i64,
+    ) -> Result<Option<Vec<AlbumRow>>, sqlx::Error> {
+        let owned: Option<(i64,)> = sqlx::query_as(
+            "SELECT l.id
+               FROM library l
+               INNER JOIN profile p ON p.id = l.profile_id
+              WHERE l.id = $1 AND l.profile_id = $2 AND p.user_id = $3",
+        )
+        .bind(library_id)
+        .bind(profile_id)
+        .bind(user_id)
+        .fetch_optional(pool)
+        .await?;
+        if owned.is_none() {
+            return Ok(None);
+        }
+        let rows = sqlx::query_as::<_, AlbumRow>(
+            "SELECT a.id,
+                    a.canonical_title,
+                    a.album_artist_id,
+                    ar.name AS album_artist_name,
+                    a.year,
+                    a.cover_hash,
+                    a.is_compilation,
+                    a.created_at,
+                    a.updated_at
+               FROM album a
+               LEFT JOIN artist ar ON ar.id = a.album_artist_id
+              WHERE a.library_id = $1
+              ORDER BY a.updated_at DESC, a.id ASC",
+        )
+        .bind(library_id)
+        .fetch_all(pool)
+        .await?;
+        Ok(Some(rows))
+    }
+
+    /// Drill-down: tracks under `album_id`, scoped to the tenant
+    /// chain `track → library → profile → user`. `Ok(None)` covers
+    /// every non-owned case (album missing / foreign library /
+    /// foreign profile / foreign user). `Ok(Some(vec![]))` is
+    /// "album owned but empty" — possible when every track linked
+    /// to it was deleted (the FK is `ON DELETE SET NULL` so the
+    /// album row outlives its tracks).
+    ///
+    /// Column projection matches `PostgresTrackRepository::
+    /// list_for_library` (NULL placeholders for the joined columns
+    /// that aren't yet stored server-side) so the resulting
+    /// `TrackRow` flows through `From<TrackRow> for TrackResponse`
+    /// unchanged. `ORDER BY disc_number, track_number` rides the
+    /// `track_album_idx` planted in the schema migration.
+    pub async fn list_tracks_for_album(
+        pool: &PgPool,
+        album_id: i64,
+        library_id: i64,
+        profile_id: i64,
+        user_id: i64,
+    ) -> Result<Option<Vec<TrackRow>>, sqlx::Error> {
+        let owned: Option<(i64,)> = sqlx::query_as(
+            "SELECT a.id
+               FROM album a
+               INNER JOIN library l ON l.id = a.library_id
+               INNER JOIN profile p ON p.id = l.profile_id
+              WHERE a.id = $1
+                AND a.library_id = $2
+                AND l.profile_id = $3
+                AND p.user_id = $4",
+        )
+        .bind(album_id)
+        .bind(library_id)
+        .bind(profile_id)
+        .bind(user_id)
+        .fetch_optional(pool)
+        .await?;
+        if owned.is_none() {
+            return Ok(None);
+        }
+        let rows = sqlx::query_as::<_, TrackRow>(
+            "SELECT t.id,
+                    t.library_id,
+                    t.title,
+                    t.album_id,
+                    NULL::text    AS album_title,
+                    NULL::bigint  AS artist_id,
+                    NULL::text    AS artist_name,
+                    NULL::text    AS artist_ids,
+                    t.duration_ms,
+                    t.track_number,
+                    t.disc_number,
+                    t.year,
+                    t.bitrate,
+                    t.sample_rate,
+                    t.channels,
+                    t.bit_depth,
+                    t.codec,
+                    t.musical_key,
+                    t.file_path,
+                    t.file_size,
+                    t.added_at,
+                    NULL::text    AS artwork_hash,
+                    NULL::text    AS artwork_format,
+                    t.rating
+               FROM track t
+              WHERE t.album_id = $1 AND t.library_id = $2
+              ORDER BY t.disc_number NULLS LAST,
+                       t.track_number NULLS LAST,
+                       t.id ASC",
+        )
+        .bind(album_id)
+        .bind(library_id)
+        .fetch_all(pool)
+        .await?;
+        Ok(Some(rows))
+    }
+}
+
+/// Artist browse helpers (Phase 4.d.0.4). Mirrors [`album`] for the
+/// `artist` table — same 2-query ownership-check shape, same 404 /
+/// 200 [] blur. Writes still go through `track_sync::upsert_artist`.
+pub mod artist {
+    use sqlx::PgPool;
+    use waveflow_core::domain::track::TrackRow;
+
+    /// Wire-shaped artist row. `picture_hash` is the BLAKE3 hex of
+    /// the artist picture in the shared metadata cache — `None`
+    /// until the artist-picture pipeline ships server-side.
+    #[derive(Debug, Clone, PartialEq, Eq, sqlx::FromRow)]
+    pub struct ArtistRow {
+        pub id: i64,
+        pub name: String,
+        pub picture_hash: Option<String>,
+        pub created_at: i64,
+        pub updated_at: i64,
+    }
+
+    /// List every artist under `(library_id, profile_id, user_id)`,
+    /// most-recently-updated first. Same 404 vs `[]` blur as
+    /// [`album::list_for_library`]. The ORDER BY rides
+    /// `artist_library_updated_idx (library_id, updated_at DESC)`.
+    pub async fn list_for_library(
+        pool: &PgPool,
+        library_id: i64,
+        profile_id: i64,
+        user_id: i64,
+    ) -> Result<Option<Vec<ArtistRow>>, sqlx::Error> {
+        let owned: Option<(i64,)> = sqlx::query_as(
+            "SELECT l.id
+               FROM library l
+               INNER JOIN profile p ON p.id = l.profile_id
+              WHERE l.id = $1 AND l.profile_id = $2 AND p.user_id = $3",
+        )
+        .bind(library_id)
+        .bind(profile_id)
+        .bind(user_id)
+        .fetch_optional(pool)
+        .await?;
+        if owned.is_none() {
+            return Ok(None);
+        }
+        let rows = sqlx::query_as::<_, ArtistRow>(
+            "SELECT id, name, picture_hash, created_at, updated_at
+               FROM artist
+              WHERE library_id = $1
+              ORDER BY updated_at DESC, id ASC",
+        )
+        .bind(library_id)
+        .fetch_all(pool)
+        .await?;
+        Ok(Some(rows))
+    }
+
+    /// Drill-down: tracks contributed by `artist_id`, scoped to the
+    /// tenant chain `track → library → profile → user`. Tracks
+    /// surface through `track_artist`, so a multi-artist track
+    /// appears under every contributor. `Ok(None)` covers every
+    /// non-owned case.
+    ///
+    /// `DISTINCT` is defensive — the `track_artist` PK
+    /// `(track_id, artist_id)` already guarantees no duplicates,
+    /// but a future schema relax (e.g. a per-version row) would
+    /// silently double-fetch without it. Cheap on Postgres because
+    /// the index is unique already. ORDER BY matches the album
+    /// drill-down for a consistent UI feel.
+    pub async fn list_tracks_for_artist(
+        pool: &PgPool,
+        artist_id: i64,
+        library_id: i64,
+        profile_id: i64,
+        user_id: i64,
+    ) -> Result<Option<Vec<TrackRow>>, sqlx::Error> {
+        let owned: Option<(i64,)> = sqlx::query_as(
+            "SELECT a.id
+               FROM artist a
+               INNER JOIN library l ON l.id = a.library_id
+               INNER JOIN profile p ON p.id = l.profile_id
+              WHERE a.id = $1
+                AND a.library_id = $2
+                AND l.profile_id = $3
+                AND p.user_id = $4",
+        )
+        .bind(artist_id)
+        .bind(library_id)
+        .bind(profile_id)
+        .bind(user_id)
+        .fetch_optional(pool)
+        .await?;
+        if owned.is_none() {
+            return Ok(None);
+        }
+        let rows = sqlx::query_as::<_, TrackRow>(
+            "SELECT DISTINCT
+                    t.id,
+                    t.library_id,
+                    t.title,
+                    t.album_id,
+                    NULL::text    AS album_title,
+                    NULL::bigint  AS artist_id,
+                    NULL::text    AS artist_name,
+                    NULL::text    AS artist_ids,
+                    t.duration_ms,
+                    t.track_number,
+                    t.disc_number,
+                    t.year,
+                    t.bitrate,
+                    t.sample_rate,
+                    t.channels,
+                    t.bit_depth,
+                    t.codec,
+                    t.musical_key,
+                    t.file_path,
+                    t.file_size,
+                    t.added_at,
+                    NULL::text    AS artwork_hash,
+                    NULL::text    AS artwork_format,
+                    t.rating
+               FROM track t
+               INNER JOIN track_artist ta ON ta.track_id = t.id
+              WHERE ta.artist_id = $1 AND t.library_id = $2
+              ORDER BY t.disc_number NULLS LAST,
+                       t.track_number NULLS LAST,
+                       t.id ASC",
+        )
+        .bind(artist_id)
+        .bind(library_id)
+        .fetch_all(pool)
+        .await?;
+        Ok(Some(rows))
+    }
+}
+
 /// Shared artwork cache helpers (Phase 1.h.1). Reads + writes against
 /// the [`metadata_artwork`] table. The bytes themselves live in
 /// `object_store` at `artwork/<hash>`; this module is the metadata
diff --git a/tests/albums.rs b/tests/albums.rs
new file mode 100644
index 0000000..2dd3283
--- /dev/null
+++ b/tests/albums.rs
@@ -0,0 +1,479 @@
+//! End-to-end tests for
+//! `/api/v1/profiles/{profile_id}/libraries/{library_id}/albums[/{id}/tracks]`
+//! (Phase 4.d.0.4).
+//!
+//! Direct SQL inserts pre-populate the `album` / `artist` /
+//! `track_artist` / `track.album_id` rows — the API has no write
+//! surface for these tables (album rows materialise from the sync
+//! apply pipeline, not from a CRUD form). Bypassing the apply path
+//! keeps the test scope tight on the read surface introduced here.
+//!
+//! Tenant isolation battery mirrors the shape of `tracks.rs`: a
+//! second authenticated caller proves a foreign user cannot pivot
+//! through their own profile id to reach user A's library.
+
+mod support;
+
+use reqwest::StatusCode;
+use serde_json::{json, Value};
+use sqlx::PgPool;
+use support::{spawn_authenticated, spawn_two_authenticated};
+
+/// Fixed sentinel for `created_at` / `updated_at`. The tests don't
+/// assert on time, so freezing the value removes nondeterminism. A
+/// per-row offset lets us pin the `updated_at DESC` ordering without
+/// time-of-day flakiness.
+const BASE_NOW_MS: i64 = 1_700_000_000_000;
+
+async fn mint_profile(base: &str, token: &str, name: &str) -> i64 {
+    let created: Value = reqwest::Client::new()
+        .post(format!("{base}/api/v1/profiles"))
+        .bearer_auth(token)
+        .json(&json!({ "name": name, "color_id": "emerald" }))
+        .send()
+        .await
+        .expect("profile create failed")
+        .error_for_status()
+        .expect("non-2xx on profile create")
+        .json()
+        .await
+        .expect("profile create body");
+    created["id"].as_i64().expect("profile id missing")
+}
+
+async fn mint_library(base: &str, token: &str, profile_id: i64, name: &str) -> i64 {
+    let created: Value = reqwest::Client::new()
+        .post(format!("{base}/api/v1/profiles/{profile_id}/libraries"))
+        .bearer_auth(token)
+        .json(&json!({ "name": name }))
+        .send()
+        .await
+        .expect("library create failed")
+        .error_for_status()
+        .expect("non-2xx on library create")
+        .json()
+        .await
+        .expect("library create body");
+    created["id"].as_i64().expect("library id missing")
+}
+
+async fn insert_artist(pool: &PgPool, library_id: i64, name: &str, now_ms: i64) -> i64 {
+    sqlx::query_scalar::<_, i64>(
+        "INSERT INTO artist (library_id, name, created_at, updated_at)
+         VALUES ($1, $2, $3, $3) RETURNING id",
+    )
+    .bind(library_id)
+    .bind(name)
+    .bind(now_ms)
+    .fetch_one(pool)
+    .await
+    .expect("insert artist")
+}
+
+async fn insert_album(
+    pool: &PgPool,
+    library_id: i64,
+    canonical_title: &str,
+    album_artist_id: Option<i64>,
+    is_compilation: bool,
+    now_ms: i64,
+) -> i64 {
+    sqlx::query_scalar::<_, i64>(
+        "INSERT INTO album
+            (library_id, canonical_title, album_artist_id,
+             is_compilation, created_at, updated_at)
+         VALUES ($1, $2, $3, $4, $5, $5) RETURNING id",
+    )
+    .bind(library_id)
+    .bind(canonical_title)
+    .bind(album_artist_id)
+    .bind(is_compilation)
+    .bind(now_ms)
+    .fetch_one(pool)
+    .await
+    .expect("insert album")
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn insert_track(
+    pool: &PgPool,
+    library_id: i64,
+    file_path: &str,
+    title: &str,
+    album_id: Option<i64>,
+    disc_number: Option<i64>,
+    track_number: Option<i64>,
+) -> i64 {
+    sqlx::query_scalar::<_, i64>(
+        "INSERT INTO track
+            (library_id, file_path, file_size, title, duration_ms,
+             album_id, disc_number, track_number, added_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9) RETURNING id",
+    )
+    .bind(library_id)
+    .bind(file_path)
+    .bind(1024_i64)
+    .bind(title)
+    .bind(180_000_i64)
+    .bind(album_id)
+    .bind(disc_number)
+    .bind(track_number)
+    .bind(BASE_NOW_MS)
+    .fetch_one(pool)
+    .await
+    .expect("insert track")
+}
+
+// ──────────────────────────────────────────────────────────────────
+// list_albums
+// ──────────────────────────────────────────────────────────────────
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_albums_empty_returns_200_empty(pool: PgPool) {
+    let auth = spawn_authenticated(pool.clone(), "u").await;
+    let profile_id = mint_profile(&auth.base, &auth.token, "Alice").await;
+    let library_id = mint_library(&auth.base, &auth.token, profile_id, "Lib").await;
+
+    let resp = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_id}/albums",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body: Vec<Value> = resp.json().await.unwrap();
+    assert!(body.is_empty());
+}
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_albums_returns_rows_ordered_by_updated_at_desc(pool: PgPool) {
+    let auth = spawn_authenticated(pool.clone(), "u").await;
+    let profile_id = mint_profile(&auth.base, &auth.token, "Alice").await;
+    let library_id = mint_library(&auth.base, &auth.token, profile_id, "Lib").await;
+
+    let artist_id = insert_artist(&pool, library_id, "Daft Punk", BASE_NOW_MS).await;
+    // Insert oldest → newest so a wrong ORDER BY surfaces in the
+    // assertion order.
+    let old = insert_album(
+        &pool,
+        library_id,
+        "Discovery",
+        Some(artist_id),
+        false,
+        BASE_NOW_MS,
+    )
+    .await;
+    let mid = insert_album(
+        &pool,
+        library_id,
+        "Random Access Memories",
+        Some(artist_id),
+        false,
+        BASE_NOW_MS + 1_000,
+    )
+    .await;
+    let new = insert_album(
+        &pool,
+        library_id,
+        "Homework",
+        Some(artist_id),
+        false,
+        BASE_NOW_MS + 2_000,
+    )
+    .await;
+
+    let body: Vec<Value> = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_id}/albums",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    let ids: Vec<i64> = body.iter().map(|v| v["id"].as_i64().unwrap()).collect();
+    assert_eq!(ids, vec![new, mid, old], "must order by updated_at DESC");
+    // album_artist_name is joined-through so the web client doesn't
+    // have to resolve N names.
+    assert_eq!(body[0]["album_artist_name"], "Daft Punk");
+    assert_eq!(body[0]["album_artist_id"].as_i64().unwrap(), artist_id);
+    assert!(!body[0]["is_compilation"].as_bool().unwrap());
+}
+
+/// `id ASC` is the documented tiebreaker when `updated_at` ties —
+/// the apply pipeline upserts a whole sync round in one transaction,
+/// so several rows can land at the same epoch millisecond. Without
+/// the tiebreaker the ordering would shuffle on each request. This
+/// test guards against a refactor that drops `, id ASC` from the
+/// ORDER BY.
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_albums_id_ascending_breaks_updated_at_ties(pool: PgPool) {
+    let auth = spawn_authenticated(pool.clone(), "u").await;
+    let profile_id = mint_profile(&auth.base, &auth.token, "Alice").await;
+    let library_id = mint_library(&auth.base, &auth.token, profile_id, "Lib").await;
+
+    // Three rows at the SAME updated_at — inserted out of natural
+    // order so a wrong tiebreaker would surface.
+    let second = insert_album(&pool, library_id, "Beta", None, false, BASE_NOW_MS).await;
+    let first = insert_album(&pool, library_id, "Alpha", None, false, BASE_NOW_MS).await;
+    let third = insert_album(&pool, library_id, "Gamma", None, false, BASE_NOW_MS).await;
+
+    let body: Vec<Value> = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_id}/albums",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    let ids: Vec<i64> = body.iter().map(|v| v["id"].as_i64().unwrap()).collect();
+    // `id ASC` on the tie — BIGSERIAL allocates monotonically so
+    // (second < first < third) by insertion order.
+    assert_eq!(ids, vec![second, first, third]);
+}
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_albums_compilation_has_null_album_artist(pool: PgPool) {
+    let auth = spawn_authenticated(pool.clone(), "u").await;
+    let profile_id = mint_profile(&auth.base, &auth.token, "Alice").await;
+    let library_id = mint_library(&auth.base, &auth.token, profile_id, "Lib").await;
+
+    insert_album(
+        &pool,
+        library_id,
+        "Now That's What I Call Music",
+        None,
+        true,
+        BASE_NOW_MS,
+    )
+    .await;
+
+    let body: Vec<Value> = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_id}/albums",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    assert_eq!(body.len(), 1);
+    assert!(body[0]["album_artist_id"].is_null());
+    assert!(body[0]["album_artist_name"].is_null());
+    assert!(body[0]["is_compilation"].as_bool().unwrap());
+}
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_albums_foreign_library_returns_404(pool: PgPool) {
+    let two = spawn_two_authenticated(pool.clone(), "a", "b").await;
+    let base = two.base.clone();
+    let profile_a = mint_profile(&base, &two.a.token, "A").await;
+    let library_a = mint_library(&base, &two.a.token, profile_a, "A's lib").await;
+    let profile_b = mint_profile(&base, &two.b.token, "B").await;
+
+    // User B pivots through their own profile id to user A's library.
+    let resp = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_b}/libraries/{library_a}/albums",
+        ))
+        .bearer_auth(&two.b.token)
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+
+    // And through user A's profile id (still not B's).
+    let resp = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_a}/libraries/{library_a}/albums",
+        ))
+        .bearer_auth(&two.b.token)
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+}
+
+// ──────────────────────────────────────────────────────────────────
+// list_album_tracks (drill-down)
+// ──────────────────────────────────────────────────────────────────
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_album_tracks_orders_by_disc_then_track_number(pool: PgPool) {
+    let auth = spawn_authenticated(pool.clone(), "u").await;
+    let profile_id = mint_profile(&auth.base, &auth.token, "Alice").await;
+    let library_id = mint_library(&auth.base, &auth.token, profile_id, "Lib").await;
+
+    let artist_id = insert_artist(&pool, library_id, "The Beatles", BASE_NOW_MS).await;
+    let album_id = insert_album(
+        &pool,
+        library_id,
+        "The Beatles (White Album)",
+        Some(artist_id),
+        false,
+        BASE_NOW_MS,
+    )
+    .await;
+    // Disc 2 / track 1 ("Birthday") inserted BEFORE Disc 1 / track 1
+    // ("Back in the U.S.S.R.") so a wrong ORDER BY surfaces.
+    let d2t1 = insert_track(
+        &pool,
+        library_id,
+        "/m/d2t1.flac",
+        "Birthday",
+        Some(album_id),
+        Some(2),
+        Some(1),
+    )
+    .await;
+    let d1t1 = insert_track(
+        &pool,
+        library_id,
+        "/m/d1t1.flac",
+        "Back in the U.S.S.R.",
+        Some(album_id),
+        Some(1),
+        Some(1),
+    )
+    .await;
+    let d1t2 = insert_track(
+        &pool,
+        library_id,
+        "/m/d1t2.flac",
+        "Dear Prudence",
+        Some(album_id),
+        Some(1),
+        Some(2),
+    )
+    .await;
+
+    let body: Vec<Value> = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_id}/albums/{album_id}/tracks",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    let ids: Vec<i64> = body.iter().map(|v| v["id"].as_i64().unwrap()).collect();
+    assert_eq!(
+        ids,
+        vec![d1t1, d1t2, d2t1],
+        "must order by (disc_number, track_number)"
+    );
+    // Every row carries the path-album id back — `TrackResponse.album_id`
+    // surfaces the materialised link so the artist-drill-down sibling
+    // endpoint can deep-link tracks to their album (Phase 4.d.0.4).
+    for row in &body {
+        assert_eq!(row["album_id"].as_i64().unwrap(), album_id);
+    }
+}
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_album_tracks_empty_album_returns_200_empty(pool: PgPool) {
+    let auth = spawn_authenticated(pool.clone(), "u").await;
+    let profile_id = mint_profile(&auth.base, &auth.token, "Alice").await;
+    let library_id = mint_library(&auth.base, &auth.token, profile_id, "Lib").await;
+
+    let album_id = insert_album(&pool, library_id, "Lone Album", None, false, BASE_NOW_MS).await;
+
+    let resp = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_id}/albums/{album_id}/tracks",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body: Vec<Value> = resp.json().await.unwrap();
+    assert!(body.is_empty());
+}
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_album_tracks_missing_album_returns_404(pool: PgPool) {
+    let auth = spawn_authenticated(pool.clone(), "u").await;
+    let profile_id = mint_profile(&auth.base, &auth.token, "Alice").await;
+    let library_id = mint_library(&auth.base, &auth.token, profile_id, "Lib").await;
+
+    let resp = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_id}/albums/9999/tracks",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+}
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_album_tracks_foreign_user_returns_404(pool: PgPool) {
+    let two = spawn_two_authenticated(pool.clone(), "a", "b").await;
+    let base = two.base.clone();
+    let profile_a = mint_profile(&base, &two.a.token, "A").await;
+    let library_a = mint_library(&base, &two.a.token, profile_a, "A's lib").await;
+    let album_a = insert_album(&pool, library_a, "Secret", None, false, BASE_NOW_MS).await;
+    let _track_a = insert_track(
+        &pool,
+        library_a,
+        "/secret.flac",
+        "Secret Track",
+        Some(album_a),
+        None,
+        None,
+    )
+    .await;
+
+    // B → A's album via A's profile id: foreign user 404.
+    let resp = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_a}/libraries/{library_a}/albums/{album_a}/tracks",
+        ))
+        .bearer_auth(&two.b.token)
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+}
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_album_tracks_wrong_library_id_returns_404(pool: PgPool) {
+    let auth = spawn_authenticated(pool.clone(), "u").await;
+    let profile_id = mint_profile(&auth.base, &auth.token, "Alice").await;
+    let library_a = mint_library(&auth.base, &auth.token, profile_id, "A").await;
+    let library_b = mint_library(&auth.base, &auth.token, profile_id, "B").await;
+    // Album lives in library_a but caller mounts it under library_b
+    // — composite scope must reject.
+    let album_a = insert_album(&pool, library_a, "X", None, false, BASE_NOW_MS).await;
+
+    let resp = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_b}/albums/{album_a}/tracks",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+}
diff --git a/tests/artists.rs b/tests/artists.rs
new file mode 100644
index 0000000..3f64873
--- /dev/null
+++ b/tests/artists.rs
@@ -0,0 +1,413 @@
+//! End-to-end tests for
+//! `/api/v1/profiles/{profile_id}/libraries/{library_id}/artists[/{id}/tracks]`
+//! (Phase 4.d.0.4).
+//!
+//! Same direct-SQL pre-population as `tests/albums.rs` — no CRUD
+//! write surface for `artist` / `track_artist`, the apply pipeline
+//! owns those rows in production. The drill-down test covers the
+//! multi-artist invariant: a track linked to two artists surfaces
+//! under both, scoped by `library_id` to stay tenant-correct.
+
+mod support;
+
+use reqwest::StatusCode;
+use serde_json::{json, Value};
+use sqlx::PgPool;
+use support::{spawn_authenticated, spawn_two_authenticated};
+
+const BASE_NOW_MS: i64 = 1_700_000_000_000;
+
+async fn mint_profile(base: &str, token: &str, name: &str) -> i64 {
+    let created: Value = reqwest::Client::new()
+        .post(format!("{base}/api/v1/profiles"))
+        .bearer_auth(token)
+        .json(&json!({ "name": name, "color_id": "emerald" }))
+        .send()
+        .await
+        .expect("profile create failed")
+        .error_for_status()
+        .expect("non-2xx on profile create")
+        .json()
+        .await
+        .expect("profile create body");
+    created["id"].as_i64().expect("profile id missing")
+}
+
+async fn mint_library(base: &str, token: &str, profile_id: i64, name: &str) -> i64 {
+    let created: Value = reqwest::Client::new()
+        .post(format!("{base}/api/v1/profiles/{profile_id}/libraries"))
+        .bearer_auth(token)
+        .json(&json!({ "name": name }))
+        .send()
+        .await
+        .expect("library create failed")
+        .error_for_status()
+        .expect("non-2xx on library create")
+        .json()
+        .await
+        .expect("library create body");
+    created["id"].as_i64().expect("library id missing")
+}
+
+async fn insert_artist(pool: &PgPool, library_id: i64, name: &str, now_ms: i64) -> i64 {
+    sqlx::query_scalar::<_, i64>(
+        "INSERT INTO artist (library_id, name, created_at, updated_at)
+         VALUES ($1, $2, $3, $3) RETURNING id",
+    )
+    .bind(library_id)
+    .bind(name)
+    .bind(now_ms)
+    .fetch_one(pool)
+    .await
+    .expect("insert artist")
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn insert_track(
+    pool: &PgPool,
+    library_id: i64,
+    file_path: &str,
+    title: &str,
+    disc_number: Option<i64>,
+    track_number: Option<i64>,
+) -> i64 {
+    sqlx::query_scalar::<_, i64>(
+        "INSERT INTO track
+            (library_id, file_path, file_size, title, duration_ms,
+             disc_number, track_number, added_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8) RETURNING id",
+    )
+    .bind(library_id)
+    .bind(file_path)
+    .bind(1024_i64)
+    .bind(title)
+    .bind(180_000_i64)
+    .bind(disc_number)
+    .bind(track_number)
+    .bind(BASE_NOW_MS)
+    .fetch_one(pool)
+    .await
+    .expect("insert track")
+}
+
+async fn insert_album(
+    pool: &PgPool,
+    library_id: i64,
+    canonical_title: &str,
+    album_artist_id: Option<i64>,
+) -> i64 {
+    sqlx::query_scalar::<_, i64>(
+        "INSERT INTO album
+            (library_id, canonical_title, album_artist_id, created_at, updated_at)
+         VALUES ($1, $2, $3, $4, $4) RETURNING id",
+    )
+    .bind(library_id)
+    .bind(canonical_title)
+    .bind(album_artist_id)
+    .bind(BASE_NOW_MS)
+    .fetch_one(pool)
+    .await
+    .expect("insert album")
+}
+
+async fn set_track_album(pool: &PgPool, track_id: i64, album_id: i64) {
+    sqlx::query("UPDATE track SET album_id = $2 WHERE id = $1")
+        .bind(track_id)
+        .bind(album_id)
+        .execute(pool)
+        .await
+        .expect("set track.album_id");
+}
+
+async fn insert_track_artist(
+    pool: &PgPool,
+    track_id: i64,
+    artist_id: i64,
+    library_id: i64,
+    position: i32,
+) {
+    sqlx::query(
+        "INSERT INTO track_artist (track_id, artist_id, library_id, position)
+         VALUES ($1, $2, $3, $4)",
+    )
+    .bind(track_id)
+    .bind(artist_id)
+    .bind(library_id)
+    .bind(position)
+    .execute(pool)
+    .await
+    .expect("insert track_artist");
+}
+
+// ──────────────────────────────────────────────────────────────────
+// list_artists
+// ──────────────────────────────────────────────────────────────────
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_artists_empty_returns_200_empty(pool: PgPool) {
+    let auth = spawn_authenticated(pool.clone(), "u").await;
+    let profile_id = mint_profile(&auth.base, &auth.token, "Alice").await;
+    let library_id = mint_library(&auth.base, &auth.token, profile_id, "Lib").await;
+
+    let resp = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_id}/artists",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body: Vec<Value> = resp.json().await.unwrap();
+    assert!(body.is_empty());
+}
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_artists_orders_by_updated_at_desc(pool: PgPool) {
+    let auth = spawn_authenticated(pool.clone(), "u").await;
+    let profile_id = mint_profile(&auth.base, &auth.token, "Alice").await;
+    let library_id = mint_library(&auth.base, &auth.token, profile_id, "Lib").await;
+
+    let old = insert_artist(&pool, library_id, "Old Artist", BASE_NOW_MS).await;
+    let mid = insert_artist(&pool, library_id, "Mid Artist", BASE_NOW_MS + 1_000).await;
+    let new = insert_artist(&pool, library_id, "New Artist", BASE_NOW_MS + 2_000).await;
+
+    let body: Vec<Value> = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_id}/artists",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    let ids: Vec<i64> = body.iter().map(|v| v["id"].as_i64().unwrap()).collect();
+    assert_eq!(ids, vec![new, mid, old]);
+    // picture_hash defaults to NULL until the server-side
+    // artist-picture pipeline ships.
+    assert!(body[0]["picture_hash"].is_null());
+}
+
+/// Tied `updated_at` rows must come back in `id ASC` order — the
+/// apply pipeline upserts a whole sync round in one transaction, so
+/// several artists can land at the same epoch millisecond. Without
+/// the tiebreaker the ordering shuffles between requests and the
+/// web client's list keeps re-keying its virtual scroller.
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_artists_id_ascending_breaks_updated_at_ties(pool: PgPool) {
+    let auth = spawn_authenticated(pool.clone(), "u").await;
+    let profile_id = mint_profile(&auth.base, &auth.token, "Alice").await;
+    let library_id = mint_library(&auth.base, &auth.token, profile_id, "Lib").await;
+
+    let second = insert_artist(&pool, library_id, "Beta", BASE_NOW_MS).await;
+    let first = insert_artist(&pool, library_id, "Alpha", BASE_NOW_MS).await;
+    let third = insert_artist(&pool, library_id, "Gamma", BASE_NOW_MS).await;
+
+    let body: Vec<Value> = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_id}/artists",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    let ids: Vec<i64> = body.iter().map(|v| v["id"].as_i64().unwrap()).collect();
+    assert_eq!(ids, vec![second, first, third]);
+}
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_artists_foreign_library_returns_404(pool: PgPool) {
+    let two = spawn_two_authenticated(pool.clone(), "a", "b").await;
+    let base = two.base.clone();
+    let profile_a = mint_profile(&base, &two.a.token, "A").await;
+    let library_a = mint_library(&base, &two.a.token, profile_a, "A's lib").await;
+    let profile_b = mint_profile(&base, &two.b.token, "B").await;
+
+    let resp = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_b}/libraries/{library_a}/artists",
+        ))
+        .bearer_auth(&two.b.token)
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+}
+
+// ──────────────────────────────────────────────────────────────────
+// list_artist_tracks (drill-down)
+// ──────────────────────────────────────────────────────────────────
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_artist_tracks_returns_every_contributor_link(pool: PgPool) {
+    let auth = spawn_authenticated(pool.clone(), "u").await;
+    let profile_id = mint_profile(&auth.base, &auth.token, "Alice").await;
+    let library_id = mint_library(&auth.base, &auth.token, profile_id, "Lib").await;
+
+    let solo = insert_artist(&pool, library_id, "Solo", BASE_NOW_MS).await;
+    let collab = insert_artist(&pool, library_id, "Collab", BASE_NOW_MS).await;
+
+    let track_a = insert_track(&pool, library_id, "/a.flac", "A", Some(1), Some(1)).await;
+    let track_duet = insert_track(&pool, library_id, "/b.flac", "B", Some(1), Some(2)).await;
+    let track_solo_only = insert_track(&pool, library_id, "/c.flac", "C", Some(1), Some(3)).await;
+    // Track A: only solo. Track B: solo + collab. Track C: only solo.
+    insert_track_artist(&pool, track_a, solo, library_id, 0).await;
+    insert_track_artist(&pool, track_duet, solo, library_id, 0).await;
+    insert_track_artist(&pool, track_duet, collab, library_id, 1).await;
+    insert_track_artist(&pool, track_solo_only, solo, library_id, 0).await;
+
+    // Solo gets all three tracks.
+    let solo_tracks: Vec<Value> = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_id}/artists/{solo}/tracks",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    let solo_ids: Vec<i64> = solo_tracks
+        .iter()
+        .map(|v| v["id"].as_i64().unwrap())
+        .collect();
+    assert_eq!(solo_ids, vec![track_a, track_duet, track_solo_only]);
+
+    // Collab gets just the duet — same track surfaces under both
+    // contributors.
+    let collab_tracks: Vec<Value> = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_id}/artists/{collab}/tracks",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    let collab_ids: Vec<i64> = collab_tracks
+        .iter()
+        .map(|v| v["id"].as_i64().unwrap())
+        .collect();
+    assert_eq!(collab_ids, vec![track_duet]);
+}
+
+/// Artist drill-down surfaces `album_id` so the web client can
+/// deep-link a contributed track to its album page without an
+/// extra `/tracks/{id}` round-trip (Phase 4.d.0.4 wire shape).
+/// Mixes album-linked + orphan tracks so the `Option<i64>`
+/// projection round-trips both states.
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_artist_tracks_surfaces_album_id_when_linked(pool: PgPool) {
+    let auth = spawn_authenticated(pool.clone(), "u").await;
+    let profile_id = mint_profile(&auth.base, &auth.token, "Alice").await;
+    let library_id = mint_library(&auth.base, &auth.token, profile_id, "Lib").await;
+
+    let artist_id = insert_artist(&pool, library_id, "Tycho", BASE_NOW_MS).await;
+    let album_id = insert_album(&pool, library_id, "Awake", Some(artist_id)).await;
+
+    // Track 1: linked to the album. Track 2: orphan (no album).
+    let linked = insert_track(&pool, library_id, "/a.flac", "A", Some(1), Some(1)).await;
+    let orphan = insert_track(&pool, library_id, "/b.flac", "B", Some(1), Some(2)).await;
+    set_track_album(&pool, linked, album_id).await;
+    insert_track_artist(&pool, linked, artist_id, library_id, 0).await;
+    insert_track_artist(&pool, orphan, artist_id, library_id, 0).await;
+
+    let body: Vec<Value> = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_id}/artists/{artist_id}/tracks",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    assert_eq!(body.len(), 2);
+    let by_id: std::collections::HashMap<i64, &Value> = body
+        .iter()
+        .map(|r| (r["id"].as_i64().unwrap(), r))
+        .collect();
+    assert_eq!(by_id[&linked]["album_id"].as_i64().unwrap(), album_id);
+    assert!(
+        by_id[&orphan]["album_id"].is_null(),
+        "orphan track must surface album_id=null"
+    );
+}
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_artist_tracks_empty_artist_returns_200_empty(pool: PgPool) {
+    let auth = spawn_authenticated(pool.clone(), "u").await;
+    let profile_id = mint_profile(&auth.base, &auth.token, "Alice").await;
+    let library_id = mint_library(&auth.base, &auth.token, profile_id, "Lib").await;
+
+    let artist_id = insert_artist(&pool, library_id, "Empty", BASE_NOW_MS).await;
+
+    let resp = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_id}/artists/{artist_id}/tracks",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body: Vec<Value> = resp.json().await.unwrap();
+    assert!(body.is_empty());
+}
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_artist_tracks_foreign_user_returns_404(pool: PgPool) {
+    let two = spawn_two_authenticated(pool.clone(), "a", "b").await;
+    let base = two.base.clone();
+    let profile_a = mint_profile(&base, &two.a.token, "A").await;
+    let library_a = mint_library(&base, &two.a.token, profile_a, "A's lib").await;
+    let artist_a = insert_artist(&pool, library_a, "Hidden", BASE_NOW_MS).await;
+    let track_a = insert_track(&pool, library_a, "/h.flac", "H", None, None).await;
+    insert_track_artist(&pool, track_a, artist_a, library_a, 0).await;
+
+    let resp = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_a}/libraries/{library_a}/artists/{artist_a}/tracks",
+        ))
+        .bearer_auth(&two.b.token)
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+}
+
+#[sqlx::test(migrator = "waveflow_server::db::MIGRATOR")]
+async fn list_artist_tracks_wrong_library_id_returns_404(pool: PgPool) {
+    let auth = spawn_authenticated(pool.clone(), "u").await;
+    let profile_id = mint_profile(&auth.base, &auth.token, "Alice").await;
+    let library_a = mint_library(&auth.base, &auth.token, profile_id, "A").await;
+    let library_b = mint_library(&auth.base, &auth.token, profile_id, "B").await;
+    let artist_a = insert_artist(&pool, library_a, "X", BASE_NOW_MS).await;
+
+    let resp = reqwest::Client::new()
+        .get(format!(
+            "{base}/api/v1/profiles/{profile_id}/libraries/{library_b}/artists/{artist_a}/tracks",
+            base = &auth.base
+        ))
+        .bearer_auth(&auth.token)
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+}
diff --git a/tests/openapi.rs b/tests/openapi.rs
index db6a745..d33d5ad 100644
--- a/tests/openapi.rs
+++ b/tests/openapi.rs
@@ -54,6 +54,29 @@ async fn openapi_doc_lists_every_handler(pool: PgPool) {
         paths.contains_key("/api/v1/profiles/{profile_id}/libraries/{library_id}/tracks/{id}"),
         "missing tracks item path in spec"
     );
+    // Phase 4.d.0.4 browse surface — drop the `#[utoipa::path]` macro
+    // from any of these and the web client stops seeing them in the
+    // docs.
+    assert!(
+        paths.contains_key("/api/v1/profiles/{profile_id}/libraries/{library_id}/albums"),
+        "missing albums collection path in spec"
+    );
+    assert!(
+        paths.contains_key(
+            "/api/v1/profiles/{profile_id}/libraries/{library_id}/albums/{id}/tracks"
+        ),
+        "missing album drill-down path in spec"
+    );
+    assert!(
+        paths.contains_key("/api/v1/profiles/{profile_id}/libraries/{library_id}/artists"),
+        "missing artists collection path in spec"
+    );
+    assert!(
+        paths.contains_key(
+            "/api/v1/profiles/{profile_id}/libraries/{library_id}/artists/{id}/tracks"
+        ),
+        "missing artist drill-down path in spec"
+    );
     assert!(
         paths.contains_key("/api/v1/profiles/{profile_id}/playlists"),
         "missing playlists collection path in spec"

From 063ad37953cfc55fdb1395a6f05d308bc1da41de Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 8 Jun 2026 03:18:16 +0200
Subject: [PATCH 2/2] docs(api): refresh module list in api/mod.rs header

CR catch on PR #36: the header still said "Future modules will cover
sync, stream" but those modules have been declared + wired into the
router since 1.f and 1.e respectively. Refresh the list so it matches
what `mod.rs` actually mounts (sync, stream, artwork, share alongside
the CRUD modules).

@coderabbitai resolved

Signed-off-by: InstaZDLL <github.105mh@8shield.net>
---
 src/api/mod.rs | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/api/mod.rs b/src/api/mod.rs
index 667e65e..31ff5ac 100644
--- a/src/api/mod.rs
+++ b/src/api/mod.rs
@@ -8,8 +8,11 @@
 //! a library, `albums.rs` + `artists.rs` cover the read-only browse
 //! surface materialised by the sync apply pipeline (phase 4.d.0.4),
 //! `playlists.rs` covers tenant-scoped playlist CRUD nested under a
-//! profile. Future modules will cover `sync`, `stream` (per RFC-001
-//! §6 / §7).
+//! profile, `sync.rs` carries the apply pipeline + WebSocket fan-out
+//! (RFC-001 §6), `stream.rs` carries the HMAC-gated audio streaming
+//! surface (RFC-001 §7), `artwork.rs` carries the shared artwork
+//! cache (phase 1.h), `share.rs` carries the public playlist share
+//! surface (phase 1.g).
 //!
 //! Versioning policy: every resource module mounts under `/api/v1/`
 //! (except `/health` and `/ready`, which are unversioned by