fix(aliases): store modal alias under raw model key + make aliases visible/manageable

The headline bug: aliases created from the modal NEVER resolved. Create
sent the normalized display name ('Sword', 'Uchiha Sasuke') while
resolution keys on the raw booru model key ('sword', 'uchiha_sasuke',
case-sensitive) — so the mapping was stored under a key nothing looks up,
and the prediction kept reappearing unaliased. The raw key wasn't even in
the /suggestions response, so the modal couldn't send it.

- Suggestion now carries raw_name (the model key an alias must use) and
  via_alias (surfaced via an operator alias); both serialized by the API.
- Modal alias-create sends raw_name, not display_name (the fix). Aliased
  suggestions show an 'alias' badge and a 'Remove alias' action; 'Treat as
  alias for…' is hidden for centroid hits (no model key) and already-aliased
  rows.
- Tag-side management: TagCard ⋮ → 'Aliases…' opens a dialog listing the
  model keys that fold into a tag, with remove (GET /api/tags/<id>/aliases +
  AliasService.list_for_tag). Creation stays in the modal suggestion flow.

Tests: full API round-trip locking the raw-key contract (raw_name exposed →
alias authored with it → resolves + via_alias on a later image);
list_for_tag (service + API); via_alias/raw_name on the existing service
suggestion tests. No migration.

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

tests/test_api_aliases.py

@@ -37,3 +37,24 @@ async def test_create_list_delete(client, db):
 async def test_create_requires_fields(client):
     resp = await client.post("/api/aliases", json={"alias_string": "x"})
     assert resp.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_list_for_tag_endpoint(client, db):
+    tag = await TagService(db).find_or_create("TagSide", TagKind.character)
+    await db.commit()
+    await client.post(
+        "/api/aliases",
+        json={
+            "alias_string": "ts_key",
+            "alias_category": "character",
+            "canonical_tag_id": tag.id,
+        },
+    )
+
+    resp = await client.get(f"/api/tags/{tag.id}/aliases")
+    assert resp.status_code == 200
+    body = await resp.get_json()
+    assert body == [{"alias_string": "ts_key", "alias_category": "character"}]
+
+    assert (await client.get("/api/tags/99999999/aliases")).status_code == 404

tests/test_api_suggestions.py

@@ -78,3 +78,66 @@ async def test_alias_requires_fields(client, db):
         f"/api/images/{img.id}/suggestions/alias", json={"alias_string": "x"}
     )
     assert resp.status_code == 400
+
+
+async def _img_at(db, path, sha, preds):
+    from tests._prediction_helpers import seed_predictions
+
+    img = ImageRecord(
+        path=path, sha256=sha, size_bytes=1, mime="image/jpeg",
+        width=1, height=1, origin="imported_filesystem",
+        integrity_status="unknown",
+    )
+    db.add(img)
+    await db.commit()
+    await seed_predictions(db, img.id, preds)
+    await db.commit()
+    return img
+
+
+@pytest.mark.asyncio
+async def test_alias_roundtrip_resolves_by_raw_key(client, db):
+    """Locks the modal-alias contract: the suggestion exposes the RAW model key,
+    an alias authored with that key resolves on a later image, and the resolved
+    suggestion is flagged via_alias. (Pre-fix the modal stored the normalized
+    display name, which never resolved.)"""
+    canonical = await TagService(db).find_or_create(
+        "Sasuke Uchiha", TagKind.character
+    )
+    await db.commit()
+    preds = {"uchiha_sasuke": {"category": "character", "confidence": 0.99}}
+    img_a = await _img_at(db, "/images/alias_a.jpg", "a" * 64, preds)
+
+    # (a) raw_name is exposed so the modal can author the alias with it; the
+    # raw prediction doesn't textually match the tag, so it'd otherwise be +new.
+    body = await (
+        await client.get(f"/api/images/{img_a.id}/suggestions")
+    ).get_json()
+    sug = body["by_category"]["character"][0]
+    assert sug["raw_name"] == "uchiha_sasuke"
+    assert sug["via_alias"] is False
+    assert sug["creates_new_tag"] is True
+
+    # Author the alias keyed by the RAW key (what the frontend now sends).
+    resp = await client.post(
+        f"/api/images/{img_a.id}/suggestions/alias",
+        json={
+            "alias_string": sug["raw_name"],
+            "alias_category": "character",
+            "canonical_tag_id": canonical.id,
+        },
+    )
+    assert resp.status_code == 204
+
+    # (b) A DIFFERENT image with the same prediction now resolves via the alias
+    # (image A's tag is applied, so it's filtered there). Had the alias been
+    # stored under the display name, this would NOT resolve.
+    img_b = await _img_at(db, "/images/alias_b.jpg", "b" * 64, preds)
+    body_b = await (
+        await client.get(f"/api/images/{img_b.id}/suggestions")
+    ).get_json()
+    sug_b = body_b["by_category"]["character"][0]
+    assert sug_b["canonical_tag_id"] == canonical.id
+    assert sug_b["via_alias"] is True
+    assert sug_b["creates_new_tag"] is False
+    assert sug_b["raw_name"] == "uchiha_sasuke"

tests/test_ml_aliases.py

@@ -83,3 +83,18 @@ async def test_list_all(db):
     await aliases.create("z1", "general", t.id)
     rows = await aliases.list_all()
     assert any(r.alias_string == "z1" and r.canonical_tag_name == "Z" for r in rows)
+
+
+@pytest.mark.asyncio
+async def test_list_for_tag(db):
+    tags = TagService(db)
+    keep = await tags.find_or_create("Keeper", TagKind.general)
+    other = await tags.find_or_create("Other", TagKind.general)
+    aliases = AliasService(db)
+    await aliases.create("k1", "general", keep.id)
+    await aliases.create("k2", "general", keep.id)
+    await aliases.create("o1", "general", other.id)
+
+    rows = await aliases.list_for_tag(keep.id)
+    assert {r.alias_string for r in rows} == {"k1", "k2"}
+    assert all(r.canonical_tag_id == keep.id for r in rows)

tests/test_ml_suggestions.py

@@ -107,6 +107,9 @@ async def test_alias_resolution(db):
     assert chars[0].display_name == "Sasuke Uchiha"
     assert chars[0].canonical_tag_id == canonical.id
     assert chars[0].creates_new_tag is False
+    # Surfaced via an alias on the raw model key — the UI marks it + offers undo.
+    assert chars[0].via_alias is True
+    assert chars[0].raw_name == "uchiha_sasuke"
 
 
 @pytest.mark.asyncio
@@ -122,6 +125,9 @@ async def test_raw_tag_creates_new(db):
     # title-cased), not the raw vocab key.
     assert chars[0].display_name == "Brand New Tag"
     assert chars[0].creates_new_tag is True
+    # Not aliased, but the raw key is carried so the modal can author one.
+    assert chars[0].via_alias is False
+    assert chars[0].raw_name == "brand_new_tag"
     assert chars[0].canonical_tag_id is None