feat: manga metadata with status, authors, genres, tags, and search filters (0.15.0)

Adds first-class manga metadata across the stack:

- **Status** (ongoing / completed), **alternative titles**, normalized
  **multi-author** support, **curated genres** (13 seeded), and
  **free-form user tags** (case-insensitive, globally shared). Each is
  modelled as its own table joined to mangas; `mangas.author` is
  backfilled into `authors` + `manga_authors` and dropped.
- New endpoints: `PATCH /v1/mangas/:id` (three-state `description`),
  `POST/DELETE /v1/mangas/:id/tags[/:tag_id]`, `GET /v1/genres`,
  `GET /v1/tags?search=`.
- `GET /v1/mangas` now returns `MangaCard` (with authors + genres
  batched in) and supports `?status=`, `?author_id=`, `?genre_id=`,
  `?tag_id=` filters — AND across facets, with empty-array no-op
  semantics for the unnest primitive.
- `GET /v1/mangas/:id` returns the enriched `MangaDetail` with tags.
- Frontend: reusable `Chip` component; manga detail page renders
  authors as chips linking to `/authors/:id` (Phase 2), a status
  badge, alt titles, genres, and tags with inline add/remove (only
  the attacher sees remove); upload form supports multi-author /
  multi-genre / alt titles / status; search page gets a collapsible
  URL-synced filter panel with keyboard-navigable tag autocomplete.
- 126 backend tests (incl. AND-across-facets primitive, case-insens
  author/tag de-dup, transactional create rollback, PATCH semantics
  for missing / null / set on description); 72 frontend tests +
  svelte-check clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/src/repo/author.rs

@@ -0,0 +1,205 @@
+//! Author persistence. Same plain-function style as the other repos.
+//!
+//! Names are stored with the casing of the first submission; lookups go
+//! through the case-insensitive unique index on `lower(name)` so
+//! "Kentaro Miura" and "kentaro miura" share one row.
+
+use std::collections::BTreeMap;
+
+use sqlx::{PgConnection, PgExecutor, PgPool};
+use uuid::Uuid;
+
+use crate::domain::author::{Author, AuthorRef, AuthorWithCount};
+use crate::domain::manga::Manga;
+use crate::error::{AppError, AppResult};
+
+/// Insert-or-find by name. Returns the canonical row whether or not
+/// this call created it. The `ON CONFLICT … DO UPDATE` no-op is what
+/// makes `RETURNING` come back even on the existing-row path.
+pub async fn upsert_by_name<'e, E: PgExecutor<'e>>(
+    executor: E,
+    name: &str,
+) -> AppResult<Author> {
+    let trimmed = name.trim();
+    if trimmed.is_empty() {
+        return Err(AppError::ValidationFailed {
+            message: "author name cannot be empty".into(),
+            details: serde_json::json!({ "authors": "non-empty names required" }),
+        });
+    }
+    let row = sqlx::query_as::<_, Author>(
+        r#"
+        INSERT INTO authors (name)
+        VALUES ($1)
+        ON CONFLICT (lower(name)) DO UPDATE SET name = authors.name
+        RETURNING id, name, created_at
+        "#,
+    )
+    .bind(trimmed)
+    .fetch_one(executor)
+    .await?;
+    Ok(row)
+}
+
+pub async fn find_by_id(pool: &PgPool, id: Uuid) -> AppResult<Author> {
+    sqlx::query_as::<_, Author>(
+        "SELECT id, name, created_at FROM authors WHERE id = $1",
+    )
+    .bind(id)
+    .fetch_optional(pool)
+    .await?
+    .ok_or(AppError::NotFound)
+}
+
+pub async fn find_with_count(pool: &PgPool, id: Uuid) -> AppResult<AuthorWithCount> {
+    sqlx::query_as::<_, AuthorWithCount>(
+        r#"
+        SELECT a.id,
+               a.name,
+               a.created_at,
+               (SELECT count(*) FROM manga_authors ma WHERE ma.author_id = a.id) AS manga_count
+          FROM authors a
+         WHERE a.id = $1
+        "#,
+    )
+    .bind(id)
+    .fetch_optional(pool)
+    .await?
+    .ok_or(AppError::NotFound)
+}
+
+/// Autocomplete-friendly: substring + trigram match on `name`, ordered
+/// most-similar first when a search term is present.
+pub async fn list(
+    pool: &PgPool,
+    search: Option<&str>,
+    limit: i64,
+    offset: i64,
+) -> AppResult<Vec<Author>> {
+    let rows = sqlx::query_as::<_, Author>(
+        r#"
+        SELECT id, name, created_at
+          FROM authors
+         WHERE $1::text IS NULL
+            OR name ILIKE '%' || $1 || '%'
+            OR name % $1
+         ORDER BY CASE WHEN $1::text IS NULL THEN 0 ELSE similarity(name, $1) END DESC,
+                  lower(name) ASC
+         LIMIT $2 OFFSET $3
+        "#,
+    )
+    .bind(search)
+    .bind(limit)
+    .bind(offset)
+    .fetch_all(pool)
+    .await?;
+    Ok(rows)
+}
+
+/// Atomically replace the set of authors on a manga. Caller passes a
+/// `&mut PgConnection` (`&mut *tx` works) so the delete+upserts run in
+/// one transaction with whatever called us.
+pub async fn set_for_manga(
+    conn: &mut PgConnection,
+    manga_id: Uuid,
+    names: &[String],
+) -> AppResult<Vec<AuthorRef>> {
+    sqlx::query("DELETE FROM manga_authors WHERE manga_id = $1")
+        .bind(manga_id)
+        .execute(&mut *conn)
+        .await?;
+
+    let mut refs = Vec::with_capacity(names.len());
+    for (position, name) in names.iter().enumerate() {
+        let author = upsert_by_name(&mut *conn, name).await?;
+        sqlx::query(
+            "INSERT INTO manga_authors (manga_id, author_id, position) VALUES ($1, $2, $3)
+             ON CONFLICT (manga_id, author_id) DO NOTHING",
+        )
+        .bind(manga_id)
+        .bind(author.id)
+        .bind(position as i32)
+        .execute(&mut *conn)
+        .await?;
+        refs.push(AuthorRef { id: author.id, name: author.name });
+    }
+    Ok(refs)
+}
+
+pub async fn list_for_manga(pool: &PgPool, manga_id: Uuid) -> AppResult<Vec<AuthorRef>> {
+    let rows = sqlx::query_as::<_, AuthorRef>(
+        r#"
+        SELECT a.id, a.name
+          FROM manga_authors ma
+          JOIN authors a ON a.id = ma.author_id
+         WHERE ma.manga_id = $1
+         ORDER BY ma.position, lower(a.name)
+        "#,
+    )
+    .bind(manga_id)
+    .fetch_all(pool)
+    .await?;
+    Ok(rows)
+}
+
+/// Batch-load authors for a list of manga ids and group by manga. Used
+/// by the list endpoint to avoid N+1 round-trips.
+pub async fn load_for_mangas(
+    pool: &PgPool,
+    manga_ids: &[Uuid],
+) -> AppResult<BTreeMap<Uuid, Vec<AuthorRef>>> {
+    if manga_ids.is_empty() {
+        return Ok(BTreeMap::new());
+    }
+    let rows: Vec<(Uuid, Uuid, String)> = sqlx::query_as(
+        r#"
+        SELECT ma.manga_id, a.id, a.name
+          FROM manga_authors ma
+          JOIN authors a ON a.id = ma.author_id
+         WHERE ma.manga_id = ANY($1)
+         ORDER BY ma.manga_id, ma.position, lower(a.name)
+        "#,
+    )
+    .bind(manga_ids)
+    .fetch_all(pool)
+    .await?;
+    let mut grouped: BTreeMap<Uuid, Vec<AuthorRef>> = BTreeMap::new();
+    for (manga_id, author_id, name) in rows {
+        grouped
+            .entry(manga_id)
+            .or_default()
+            .push(AuthorRef { id: author_id, name });
+    }
+    Ok(grouped)
+}
+
+pub async fn list_mangas_for_author(
+    pool: &PgPool,
+    author_id: Uuid,
+    limit: i64,
+    offset: i64,
+) -> AppResult<(Vec<Manga>, i64)> {
+    let rows = sqlx::query_as::<_, Manga>(
+        r#"
+        SELECT m.id, m.title, m.status, m.alt_titles, m.description,
+               m.cover_image_path, m.created_at, m.updated_at
+          FROM manga_authors ma
+          JOIN mangas m ON m.id = ma.manga_id
+         WHERE ma.author_id = $1
+         ORDER BY m.created_at DESC, m.id
+         LIMIT $2 OFFSET $3
+        "#,
+    )
+    .bind(author_id)
+    .bind(limit)
+    .bind(offset)
+    .fetch_all(pool)
+    .await?;
+    let (total,): (i64,) = sqlx::query_as(
+        "SELECT count(*) FROM manga_authors WHERE author_id = $1",
+    )
+    .bind(author_id)
+    .fetch_one(pool)
+    .await?;
+    Ok((rows, total))
+}

backend/src/repo/genre.rs

@@ -0,0 +1,88 @@
+use std::collections::BTreeMap;
+
+use sqlx::{PgConnection, PgPool};
+use uuid::Uuid;
+
+use crate::domain::genre::{Genre, GenreRef};
+use crate::error::AppResult;
+
+pub async fn list_all(pool: &PgPool) -> AppResult<Vec<Genre>> {
+    let rows = sqlx::query_as::<_, Genre>(
+        "SELECT id, name FROM genres ORDER BY lower(name)",
+    )
+    .fetch_all(pool)
+    .await?;
+    Ok(rows)
+}
+
+pub async fn list_for_manga(pool: &PgPool, manga_id: Uuid) -> AppResult<Vec<GenreRef>> {
+    let rows = sqlx::query_as::<_, GenreRef>(
+        r#"
+        SELECT g.id, g.name
+          FROM manga_genres mg
+          JOIN genres g ON g.id = mg.genre_id
+         WHERE mg.manga_id = $1
+         ORDER BY lower(g.name)
+        "#,
+    )
+    .bind(manga_id)
+    .fetch_all(pool)
+    .await?;
+    Ok(rows)
+}
+
+pub async fn load_for_mangas(
+    pool: &PgPool,
+    manga_ids: &[Uuid],
+) -> AppResult<BTreeMap<Uuid, Vec<GenreRef>>> {
+    if manga_ids.is_empty() {
+        return Ok(BTreeMap::new());
+    }
+    let rows: Vec<(Uuid, Uuid, String)> = sqlx::query_as(
+        r#"
+        SELECT mg.manga_id, g.id, g.name
+          FROM manga_genres mg
+          JOIN genres g ON g.id = mg.genre_id
+         WHERE mg.manga_id = ANY($1)
+         ORDER BY mg.manga_id, lower(g.name)
+        "#,
+    )
+    .bind(manga_ids)
+    .fetch_all(pool)
+    .await?;
+    let mut grouped: BTreeMap<Uuid, Vec<GenreRef>> = BTreeMap::new();
+    for (manga_id, id, name) in rows {
+        grouped.entry(manga_id).or_default().push(GenreRef { id, name });
+    }
+    Ok(grouped)
+}
+
+/// Replace the manga's genres. Unknown ids are silently ignored: the
+/// FK constraint would reject them, so we filter upstream rather than
+/// surface a 500 here. (The API layer validates the set against
+/// `list_all` first.)
+pub async fn set_for_manga(
+    conn: &mut PgConnection,
+    manga_id: Uuid,
+    genre_ids: &[Uuid],
+) -> AppResult<()> {
+    sqlx::query("DELETE FROM manga_genres WHERE manga_id = $1")
+        .bind(manga_id)
+        .execute(&mut *conn)
+        .await?;
+    if genre_ids.is_empty() {
+        return Ok(());
+    }
+    sqlx::query(
+        r#"
+        INSERT INTO manga_genres (manga_id, genre_id)
+        SELECT $1, unnest($2::uuid[])
+        ON CONFLICT DO NOTHING
+        "#,
+    )
+    .bind(manga_id)
+    .bind(genre_ids)
+    .execute(&mut *conn)
+    .await?;
+    Ok(())
+}

backend/src/repo/manga.rs

@@ -6,11 +6,17 @@
 //! a trait + impl if a second backend ever becomes necessary.
 
 use serde::Deserialize;
-use sqlx::{PgExecutor, PgPool};
+use sqlx::{PgConnection, PgExecutor, PgPool};
 use uuid::Uuid;
 
-use crate::domain::manga::{Manga, NewManga};
+use crate::domain::manga::{Manga, MangaCard, MangaDetail};
 use crate::error::{AppError, AppResult};
+use crate::repo;
+
+/// Status values mirror the CHECK constraint in 0009. Centralized so
+/// the API layer can validate uploads against the same vocabulary.
+pub const STATUSES: &[&str] = &["ongoing", "completed"];
+pub const DEFAULT_STATUS: &str = "ongoing";
 
 #[derive(Debug, Clone, Copy, Default, Deserialize)]
 #[serde(rename_all = "snake_case")]
@@ -22,28 +28,65 @@ pub enum ListSort {
     Title,
 }
 
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, Default)]
 pub struct ListQuery {
     pub search: Option<String>,
+    pub status: Option<String>,
+    pub author_ids: Vec<Uuid>,
+    pub genre_ids: Vec<Uuid>,
+    pub tag_ids: Vec<Uuid>,
     pub limit: i64,
     pub offset: i64,
     pub sort: ListSort,
 }
 
-impl Default for ListQuery {
-    fn default() -> Self {
-        Self {
-            search: None,
-            limit: 50,
-            offset: 0,
-            sort: ListSort::Recent,
-        }
-    }
-}
+const SELECT_COLS: &str =
+    "id, title, status, alt_titles, description, cover_image_path, created_at, updated_at";
+
+/// Shared WHERE used by both the rows and the count queries. Filters
+/// are AND across facets: every supplied author_id (or genre, or tag)
+/// must be attached to the manga for it to match. Empty arrays mean
+/// "no filter" because `NOT EXISTS` over an empty unnest is vacuously
+/// true.
+const FILTER_WHERE: &str = r#"
+    ($1::text IS NULL
+     OR title ILIKE '%' || $1 || '%'
+     OR title % $1
+     OR EXISTS (
+            SELECT 1 FROM manga_authors ma
+              JOIN authors a ON a.id = ma.author_id
+             WHERE ma.manga_id = mangas.id
+               AND (a.name ILIKE '%' || $1 || '%' OR a.name % $1)
+        )
+    )
+    AND ($2::text IS NULL OR status = $2)
+    AND NOT EXISTS (
+        SELECT 1 FROM unnest($3::uuid[]) AS req(id)
+         WHERE NOT EXISTS (
+                SELECT 1 FROM manga_authors ma
+                 WHERE ma.manga_id = mangas.id AND ma.author_id = req.id
+             )
+    )
+    AND NOT EXISTS (
+        SELECT 1 FROM unnest($4::uuid[]) AS req(id)
+         WHERE NOT EXISTS (
+                SELECT 1 FROM manga_genres mg
+                 WHERE mg.manga_id = mangas.id AND mg.genre_id = req.id
+             )
+    )
+    AND NOT EXISTS (
+        SELECT 1 FROM unnest($5::uuid[]) AS req(id)
+         WHERE NOT EXISTS (
+                SELECT 1 FROM manga_tags mt
+                 WHERE mt.manga_id = mangas.id AND mt.tag_id = req.id
+             )
+    )
+"#;
 
 /// Returns the page of mangas matching `query` plus the unfiltered total
-/// count for the same filter. The trigram GIN indexes (see 0005_search.sql)
-/// keep both queries cheap as the library grows.
+/// count for the same filter. The trigram GIN indexes (see 0005_search.sql
+/// and 0009_manga_metadata.sql) keep both queries cheap as the library
+/// grows.
 pub async fn list(pool: &PgPool, query: &ListQuery) -> AppResult<(Vec<Manga>, i64)> {
     // `order_by` is interpolated from a hard-coded enum, never from request
     // input, so this is not a SQL injection seam.
@@ -53,80 +96,152 @@ pub async fn list(pool: &PgPool, query: &ListQuery) -> AppResult<(Vec<Manga>, i6
     };
 
     let search = query.search.as_deref();
+    let status = query.status.as_deref();
 
     let list_sql = format!(
         r#"
-        SELECT id, title, author, description, cover_image_path, created_at, updated_at
+        SELECT {SELECT_COLS}
         FROM mangas
-        WHERE $1::text IS NULL
-           OR title ILIKE '%' || $1 || '%'
-           OR COALESCE(author, '') ILIKE '%' || $1 || '%'
-           OR title % $1
-           OR (author IS NOT NULL AND author % $1)
+        WHERE {FILTER_WHERE}
         ORDER BY {order_by}
-        LIMIT $2 OFFSET $3
+        LIMIT $6 OFFSET $7
         "#
     );
 
     let rows = sqlx::query_as::<_, Manga>(&list_sql)
         .bind(search)
+        .bind(status)
+        .bind(&query.author_ids)
+        .bind(&query.genre_ids)
+        .bind(&query.tag_ids)
         .bind(query.limit)
         .bind(query.offset)
         .fetch_all(pool)
         .await?;
 
-    let count_sql = r#"
+    let count_sql = format!(
+        r#"
         SELECT count(*) FROM mangas
-        WHERE $1::text IS NULL
-           OR title ILIKE '%' || $1 || '%'
-           OR COALESCE(author, '') ILIKE '%' || $1 || '%'
-           OR title % $1
-           OR (author IS NOT NULL AND author % $1)
-    "#;
-    let (total,): (i64,) = sqlx::query_as(count_sql)
+        WHERE {FILTER_WHERE}
+        "#
+    );
+    let (total,): (i64,) = sqlx::query_as(&count_sql)
         .bind(search)
+        .bind(status)
+        .bind(&query.author_ids)
+        .bind(&query.genre_ids)
+        .bind(&query.tag_ids)
         .fetch_one(pool)
         .await?;
 
     Ok((rows, total))
 }
 
+/// Same filter as `list`, but wraps each row with its authors + genres
+/// in a single batched round-trip. Tags are intentionally not loaded
+/// here — see `MangaCard` in the domain layer.
+pub async fn list_cards(
+    pool: &PgPool,
+    query: &ListQuery,
+) -> AppResult<(Vec<MangaCard>, i64)> {
+    let (rows, total) = list(pool, query).await?;
+    let ids: Vec<Uuid> = rows.iter().map(|m| m.id).collect();
+    let mut authors = repo::author::load_for_mangas(pool, &ids).await?;
+    let mut genres = repo::genre::load_for_mangas(pool, &ids).await?;
+    let cards = rows
+        .into_iter()
+        .map(|manga| MangaCard {
+            authors: authors.remove(&manga.id).unwrap_or_default(),
+            genres: genres.remove(&manga.id).unwrap_or_default(),
+            manga,
+        })
+        .collect();
+    Ok((cards, total))
+}
+
 pub async fn get(pool: &PgPool, id: Uuid) -> AppResult<Manga> {
-    sqlx::query_as::<_, Manga>(
-        r#"
-        SELECT id, title, author, description, cover_image_path, created_at, updated_at
-        FROM mangas
-        WHERE id = $1
-        "#,
-    )
+    sqlx::query_as::<_, Manga>(&format!(
+        "SELECT {SELECT_COLS} FROM mangas WHERE id = $1"
+    ))
     .bind(id)
     .fetch_optional(pool)
     .await?
     .ok_or(AppError::NotFound)
 }
 
-/// Accepts any `PgExecutor` so callers can pass `&PgPool` for simple
-/// inserts or `&mut *tx` to run inside a transaction. Same applies to
-/// `set_cover_image_path` below.
+pub async fn get_detail(pool: &PgPool, id: Uuid) -> AppResult<MangaDetail> {
+    let manga = get(pool, id).await?;
+    let authors = repo::author::list_for_manga(pool, id).await?;
+    let genres = repo::genre::list_for_manga(pool, id).await?;
+    let tags = repo::tag::list_for_manga(pool, id).await?;
+    Ok(MangaDetail { manga, authors, genres, tags })
+}
+
+/// Insert just the manga row. Relations (authors, genres) are written
+/// by the caller via `repo::author::set_for_manga` etc. in the same
+/// transaction. `status` is taken as a validated string — the handler
+/// is responsible for defaulting/validating it.
 pub async fn create<'e, E: PgExecutor<'e>>(
     executor: E,
-    input: NewManga,
+    title: &str,
+    status: &str,
+    description: Option<&str>,
+    alt_titles: &[String],
 ) -> AppResult<Manga> {
-    let row = sqlx::query_as::<_, Manga>(
+    let row = sqlx::query_as::<_, Manga>(&format!(
         r#"
-        INSERT INTO mangas (title, author, description)
-        VALUES ($1, $2, $3)
-        RETURNING id, title, author, description, cover_image_path, created_at, updated_at
-        "#,
-    )
-    .bind(&input.title)
-    .bind(&input.author)
-    .bind(&input.description)
+        INSERT INTO mangas (title, status, description, alt_titles)
+        VALUES ($1, $2, $3, $4)
+        RETURNING {SELECT_COLS}
+        "#
+    ))
+    .bind(title)
+    .bind(status)
+    .bind(description)
+    .bind(alt_titles)
     .fetch_one(executor)
     .await?;
     Ok(row)
 }
 
+/// Patch the inline columns. Each `Option` argument leaves the field
+/// untouched when `None`. `description` uses two binds — a `provided`
+/// boolean and the new value — so callers can distinguish "leave
+/// alone" from "set to NULL" (both look the same in a plain
+/// `Option<&str>` because serde collapses missing and explicit-null).
+pub async fn update_basics(
+    conn: &mut PgConnection,
+    id: Uuid,
+    title: Option<&str>,
+    status: Option<&str>,
+    description_provided: bool,
+    description: Option<&str>,
+    alt_titles: Option<&[String]>,
+) -> AppResult<Manga> {
+    let row = sqlx::query_as::<_, Manga>(&format!(
+        r#"
+        UPDATE mangas
+           SET title       = COALESCE($2, title),
+               status      = COALESCE($3, status),
+               description = CASE WHEN $4::boolean THEN $5 ELSE description END,
+               alt_titles  = COALESCE($6, alt_titles),
+               updated_at  = now()
+         WHERE id = $1
+        RETURNING {SELECT_COLS}
+        "#
+    ))
+    .bind(id)
+    .bind(title)
+    .bind(status)
+    .bind(description_provided)
+    .bind(description)
+    .bind(alt_titles)
+    .fetch_optional(&mut *conn)
+    .await?
+    .ok_or(AppError::NotFound)?;
+    Ok(row)
+}
+
 pub async fn set_cover_image_path<'e, E: PgExecutor<'e>>(
     executor: E,
     id: Uuid,
@@ -139,3 +254,12 @@ pub async fn set_cover_image_path<'e, E: PgExecutor<'e>>(
         .await?;
     Ok(())
 }
+
+pub async fn exists(pool: &PgPool, id: Uuid) -> AppResult<bool> {
+    let (exists,): (bool,) =
+        sqlx::query_as("SELECT EXISTS(SELECT 1 FROM mangas WHERE id = $1)")
+            .bind(id)
+            .fetch_one(pool)
+            .await?;
+    Ok(exists)
+}

backend/src/repo/mod.rs

@@ -1,8 +1,11 @@
 pub mod api_token;
+pub mod author;
 pub mod bookmark;
 pub mod chapter;
+pub mod genre;
 pub mod manga;
 pub mod page;
 pub mod session;
+pub mod tag;
 pub mod user;
 pub mod user_preferences;

backend/src/repo/tag.rs

@@ -0,0 +1,149 @@
+use sqlx::{PgExecutor, PgPool};
+use uuid::Uuid;
+
+use crate::domain::tag::{Tag, TagRef};
+use crate::error::{AppError, AppResult};
+
+/// True when this manga-tag attachment is new (so the API can return
+/// 201 vs 200), plus the canonical tag row.
+pub struct AttachOutcome {
+    pub tag: Tag,
+    pub created_attachment: bool,
+}
+
+pub async fn upsert_by_name<'e, E: PgExecutor<'e>>(
+    executor: E,
+    name: &str,
+) -> AppResult<Tag> {
+    let trimmed = name.trim();
+    if trimmed.is_empty() {
+        return Err(AppError::ValidationFailed {
+            message: "tag name cannot be empty".into(),
+            details: serde_json::json!({ "name": "required" }),
+        });
+    }
+    if trimmed.chars().count() > 64 {
+        return Err(AppError::ValidationFailed {
+            message: "tag name too long".into(),
+            details: serde_json::json!({ "name": "max 64 characters" }),
+        });
+    }
+    let row = sqlx::query_as::<_, Tag>(
+        r#"
+        INSERT INTO tags (name)
+        VALUES ($1)
+        ON CONFLICT (lower(name)) DO UPDATE SET name = tags.name
+        RETURNING id, name, created_at
+        "#,
+    )
+    .bind(trimmed)
+    .fetch_one(executor)
+    .await?;
+    Ok(row)
+}
+
+/// Attach a tag to a manga, idempotently. Returns whether a new
+/// attachment row was created so the API can pick 201 vs 200.
+pub async fn attach_to_manga(
+    pool: &PgPool,
+    manga_id: Uuid,
+    name: &str,
+    added_by: Uuid,
+) -> AppResult<AttachOutcome> {
+    let mut tx = pool.begin().await?;
+    let tag = upsert_by_name(&mut *tx, name).await?;
+    let rows_affected = sqlx::query(
+        r#"
+        INSERT INTO manga_tags (manga_id, tag_id, added_by)
+        VALUES ($1, $2, $3)
+        ON CONFLICT (manga_id, tag_id) DO NOTHING
+        "#,
+    )
+    .bind(manga_id)
+    .bind(tag.id)
+    .bind(added_by)
+    .execute(&mut *tx)
+    .await?
+    .rows_affected();
+    tx.commit().await?;
+    Ok(AttachOutcome { tag, created_attachment: rows_affected > 0 })
+}
+
+/// Look up who attached a given (manga, tag) pair, if any. Returns
+/// `None` if the attachment doesn't exist. The outer `AppResult` only
+/// surfaces DB errors.
+pub async fn find_attacher(
+    pool: &PgPool,
+    manga_id: Uuid,
+    tag_id: Uuid,
+) -> AppResult<Option<Option<Uuid>>> {
+    let row: Option<(Option<Uuid>,)> = sqlx::query_as(
+        "SELECT added_by FROM manga_tags WHERE manga_id = $1 AND tag_id = $2",
+    )
+    .bind(manga_id)
+    .bind(tag_id)
+    .fetch_optional(pool)
+    .await?;
+    Ok(row.map(|(added_by,)| added_by))
+}
+
+pub async fn detach(pool: &PgPool, manga_id: Uuid, tag_id: Uuid) -> AppResult<()> {
+    sqlx::query("DELETE FROM manga_tags WHERE manga_id = $1 AND tag_id = $2")
+        .bind(manga_id)
+        .bind(tag_id)
+        .execute(pool)
+        .await?;
+    Ok(())
+}
+
+pub async fn list_for_manga(pool: &PgPool, manga_id: Uuid) -> AppResult<Vec<TagRef>> {
+    let rows = sqlx::query_as::<_, TagRef>(
+        r#"
+        SELECT t.id, t.name, mt.added_by
+          FROM manga_tags mt
+          JOIN tags t ON t.id = mt.tag_id
+         WHERE mt.manga_id = $1
+         ORDER BY lower(t.name)
+        "#,
+    )
+    .bind(manga_id)
+    .fetch_all(pool)
+    .await?;
+    Ok(rows)
+}
+
+/// Tag autocomplete. Substring + trigram, no `added_by` (tags are
+/// global), capped at the caller's limit.
+pub async fn list(
+    pool: &PgPool,
+    search: Option<&str>,
+    limit: i64,
+) -> AppResult<Vec<Tag>> {
+    let rows = sqlx::query_as::<_, Tag>(
+        r#"
+        SELECT id, name, created_at
+          FROM tags
+         WHERE $1::text IS NULL
+            OR name ILIKE '%' || $1 || '%'
+            OR name % $1
+         ORDER BY CASE WHEN $1::text IS NULL THEN 0 ELSE similarity(name, $1) END DESC,
+                  lower(name) ASC
+         LIMIT $2
+        "#,
+    )
+    .bind(search)
+    .bind(limit)
+    .fetch_all(pool)
+    .await?;
+    Ok(rows)
+}
+
+pub async fn find_by_id(pool: &PgPool, id: Uuid) -> AppResult<Tag> {
+    sqlx::query_as::<_, Tag>(
+        "SELECT id, name, created_at FROM tags WHERE id = $1",
+    )
+    .bind(id)
+    .fetch_optional(pool)
+    .await?
+    .ok_or(AppError::NotFound)
+}