From 5c3f8ebd703912a6a37182bd17f31ed2ccbfe587 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Fri, 12 Jun 2026 13:05:58 -0400
Subject: [PATCH] fix(aliases): store modal alias under raw model key + make
 aliases visible/manageable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 backend/app/api/suggestions.py                |  5 +
 backend/app/api/tags.py                       | 20 ++++
 backend/app/services/ml/aliases.py            | 25 +++++
 backend/app/services/ml/suggestions.py        | 19 ++++
 .../components/discovery/TagAliasesDialog.vue | 99 +++++++++++++++++++
 frontend/src/components/discovery/TagCard.vue |  6 ++
 .../src/components/modal/SuggestionItem.vue   | 28 +++++-
 .../modal/SuggestionsCategoryGroup.vue        |  3 +-
 .../src/components/modal/SuggestionsPanel.vue | 17 +++-
 frontend/src/stores/suggestions.js            | 26 ++++-
 frontend/src/views/TagsView.vue               | 19 +++-
 tests/test_api_aliases.py                     | 21 ++++
 tests/test_api_suggestions.py                 | 63 ++++++++++++
 tests/test_ml_aliases.py                      | 15 +++
 tests/test_ml_suggestions.py                  |  6 ++
 15 files changed, 364 insertions(+), 8 deletions(-)
 create mode 100644 frontend/src/components/discovery/TagAliasesDialog.vue

diff --git a/backend/app/api/suggestions.py b/backend/app/api/suggestions.py
index 61fbbb7..a8a9cf4 100644
--- a/backend/app/api/suggestions.py
+++ b/backend/app/api/suggestions.py
@@ -37,6 +37,11 @@ async def get_suggestions(image_id: int):
                         "score": round(s.score, 4),
                         "source": s.source,
                         "creates_new_tag": s.creates_new_tag,
+                        # raw model key (alias is stored under this) + whether an
+                        # operator alias produced this suggestion — drive the
+                        # modal's "Treat as alias"/"Remove alias" affordances.
+                        "raw_name": s.raw_name,
+                        "via_alias": s.via_alias,
                     }
                     for s in items
                 ]
diff --git a/backend/app/api/tags.py b/backend/app/api/tags.py
index 3ab53a9..0556ed9 100644
--- a/backend/app/api/tags.py
+++ b/backend/app/api/tags.py
@@ -8,6 +8,7 @@ from ..extensions import get_session
 from ..models import Tag, TagKind
 from ..models.tag_allowlist import TagAllowlist
 from ..services.bulk_tag_service import BulkTagService
+from ..services.ml.aliases import AliasService
 from ..services.series_match_service import SeriesMatchService
 from ..services.series_service import SeriesError, SeriesService
 from ..services.tag_directory_service import TagDirectoryService
@@ -200,6 +201,25 @@ async def get_tag(tag_id: int):
         )
 
 
+@tags_bp.route("/tags/<int:tag_id>/aliases", methods=["GET"])
+async def list_tag_aliases(tag_id: int):
+    """Model keys that fold into this tag (tag-side alias view). Remove via the
+    shared DELETE /api/aliases/<string>/<category>."""
+    async with get_session() as session:
+        if await session.get(Tag, tag_id) is None:
+            return jsonify({"error": "tag not found"}), 404
+        rows = await AliasService(session).list_for_tag(tag_id)
+    return jsonify(
+        [
+            {
+                "alias_string": r.alias_string,
+                "alias_category": r.alias_category,
+            }
+            for r in rows
+        ]
+    )
+
+
 @tags_bp.route("/tags/<int:tag_id>", methods=["PATCH"])
 async def update_tag(tag_id: int):
     """Rename and/or re-fandom a tag. Body may carry `name` and/or
diff --git a/backend/app/services/ml/aliases.py b/backend/app/services/ml/aliases.py
index 479e378..c119c36 100644
--- a/backend/app/services/ml/aliases.py
+++ b/backend/app/services/ml/aliases.py
@@ -81,6 +81,31 @@ class AliasService:
             .where(TagAlias.alias_category == alias_category)
         )
 
+    async def list_for_tag(self, canonical_tag_id: int) -> Sequence[AliasRow]:
+        """Aliases that resolve TO this tag — drives the tag-side 'Aliases'
+        view (see/remove the model keys that fold into a tag)."""
+        stmt = (
+            select(
+                TagAlias.alias_string,
+                TagAlias.alias_category,
+                TagAlias.canonical_tag_id,
+                Tag.name,
+            )
+            .join(Tag, Tag.id == TagAlias.canonical_tag_id)
+            .where(TagAlias.canonical_tag_id == canonical_tag_id)
+            .order_by(TagAlias.alias_string.asc())
+        )
+        rows = (await self.session.execute(stmt)).all()
+        return [
+            AliasRow(
+                alias_string=r[0],
+                alias_category=r[1],
+                canonical_tag_id=r[2],
+                canonical_tag_name=r[3],
+            )
+            for r in rows
+        ]
+
     async def list_all(self) -> Sequence[AliasRow]:
         stmt = (
             select(
diff --git a/backend/app/services/ml/suggestions.py b/backend/app/services/ml/suggestions.py
index ca60c30..7b0f996 100644
--- a/backend/app/services/ml/suggestions.py
+++ b/backend/app/services/ml/suggestions.py
@@ -31,6 +31,14 @@ class Suggestion:
     score: float
     source: str  # 'tagger' | 'centroid' | 'both'
     creates_new_tag: bool
+    # raw_name = the booru model vocab key behind this suggestion. It's the key
+    # an alias MUST be stored under (resolution looks up the raw key), so the
+    # modal needs it to author an alias correctly. None for centroid-only hits
+    # (no underlying prediction → nothing to alias).
+    raw_name: str | None = None
+    # via_alias = this suggestion was surfaced because an operator alias remapped
+    # the raw prediction to this canonical tag. Lets the UI mark it + offer undo.
+    via_alias: bool = False
 
 
 @dataclass
@@ -161,6 +169,11 @@ class SuggestionService:
                     if existing.source != sug.source
                     else existing.source,
                     creates_new_tag=existing.creates_new_tag,
+                    # Keep the alias identity from `existing`: the tagger pass
+                    # (which carries raw_name / via_alias) runs before centroid
+                    # augmentation, so it's always the first writer for a key.
+                    raw_name=existing.raw_name,
+                    via_alias=existing.via_alias,
                 )
 
         for raw, display, category, conf in candidates:
@@ -177,6 +190,8 @@ class SuggestionService:
                         score=conf,
                         source="tagger",
                         creates_new_tag=False,
+                        raw_name=raw,
+                        via_alias=True,
                     ),
                 )
             else:
@@ -208,6 +223,8 @@ class SuggestionService:
                             score=conf,
                             source="tagger",
                             creates_new_tag=False,
+                            raw_name=raw,
+                            via_alias=False,
                         ),
                     )
                 else:
@@ -220,6 +237,8 @@ class SuggestionService:
                             score=conf,
                             source="tagger",
                             creates_new_tag=True,
+                            raw_name=raw,
+                            via_alias=False,
                         ),
                     )
 
diff --git a/frontend/src/components/discovery/TagAliasesDialog.vue b/frontend/src/components/discovery/TagAliasesDialog.vue
new file mode 100644
index 0000000..c9bd385
--- /dev/null
+++ b/frontend/src/components/discovery/TagAliasesDialog.vue
@@ -0,0 +1,99 @@
+<template>
+  <v-card>
+    <v-card-title class="fc-aliasdlg__title">
+      Aliases for <strong>{{ tag?.name }}</strong>
+    </v-card-title>
+    <v-card-text>
+      <p class="text-caption mb-3">
+        Model keys the tagger predicts that resolve to this tag — so a prediction
+        like <code>{{ exampleKey }}</code> shows as “{{ tag?.name }}” instead of a
+        separate tag. Create new aliases from a suggestion’s ⋮ menu in the image
+        view; here you can see and remove them.
+      </p>
+
+      <div v-if="loading" class="fc-aliasdlg__loading">
+        <v-progress-circular indeterminate color="accent" size="24" />
+      </div>
+      <v-alert v-else-if="error" type="error" variant="tonal" density="compact">
+        {{ error }}
+      </v-alert>
+      <div v-else-if="rows.length === 0" class="text-caption fc-aliasdlg__empty">
+        No aliases yet. In the image view, open a tagger suggestion’s ⋮ menu and
+        choose “Treat as alias for…” to map it to this tag.
+      </div>
+      <v-list v-else density="compact" class="fc-aliasdlg__list">
+        <v-list-item
+          v-for="r in rows" :key="`${r.alias_string}/${r.alias_category}`"
+        >
+          <template #prepend>
+            <code class="fc-aliasdlg__key">{{ r.alias_string }}</code>
+          </template>
+          <v-list-item-subtitle>{{ r.alias_category }}</v-list-item-subtitle>
+          <template #append>
+            <v-btn
+              icon="mdi-delete" size="x-small" variant="text" color="error"
+              :aria-label="`Remove alias ${r.alias_string}`"
+              @click="remove(r)"
+            />
+          </template>
+        </v-list-item>
+      </v-list>
+    </v-card-text>
+    <v-card-actions>
+      <v-spacer />
+      <v-btn @click="$emit('close')">Close</v-btn>
+    </v-card-actions>
+  </v-card>
+</template>
+
+<script setup>
+import { computed, onMounted, ref } from 'vue'
+import { useApi } from '../../composables/useApi.js'
+
+const props = defineProps({ tag: { type: Object, required: true } })
+defineEmits(['close'])
+
+const api = useApi()
+const rows = ref([])
+const loading = ref(false)
+const error = ref(null)
+
+// Illustrative booru-style key for the helper copy (lowercase, underscores).
+const exampleKey = computed(() =>
+  (props.tag?.name || 'tag').toLowerCase().replace(/\s+/g, '_')
+)
+
+async function reload() {
+  loading.value = true
+  error.value = null
+  try {
+    rows.value = await api.get(`/api/tags/${props.tag.id}/aliases`)
+  } catch (e) {
+    error.value = e.message || String(e)
+  } finally {
+    loading.value = false
+  }
+}
+
+async function remove(r) {
+  await api.delete(
+    `/api/aliases/${encodeURIComponent(r.alias_string)}/${encodeURIComponent(r.alias_category)}`
+  )
+  rows.value = rows.value.filter(
+    x => !(x.alias_string === r.alias_string && x.alias_category === r.alias_category)
+  )
+}
+
+onMounted(reload)
+</script>
+
+<style scoped>
+.fc-aliasdlg__loading,
+.fc-aliasdlg__empty { padding: 12px 0; }
+.fc-aliasdlg__key,
+code {
+  background: rgb(var(--v-theme-surface-light));
+  padding: 1px 6px; border-radius: 4px;
+  font-family: 'JetBrains Mono', monospace; font-size: 12px;
+}
+</style>
diff --git a/frontend/src/components/discovery/TagCard.vue b/frontend/src/components/discovery/TagCard.vue
index 81e5376..1d1a0b1 100644
--- a/frontend/src/components/discovery/TagCard.vue
+++ b/frontend/src/components/discovery/TagCard.vue
@@ -53,6 +53,11 @@
               prepend-icon="mdi-book-open-page-variant"
               @click="$emit('set-fandom', card)"
             />
+            <v-list-item
+              title="Aliases…"
+              prepend-icon="mdi-tag-multiple"
+              @click="$emit('aliases', card)"
+            />
             <v-list-item
               title="Merge with…"
               prepend-icon="mdi-call-merge"
@@ -78,6 +83,7 @@ import KebabMenu from '../common/KebabMenu.vue'
 const props = defineProps({ card: { type: Object, required: true } })
 const emit = defineEmits([
   'open', 'rename', 'manage', 'read', 'merge-with', 'delete', 'set-fandom',
+  'aliases',
 ])
 
 const editing = ref(false)
diff --git a/frontend/src/components/modal/SuggestionItem.vue b/frontend/src/components/modal/SuggestionItem.vue
index ed0b972..1b79848 100644
--- a/frontend/src/components/modal/SuggestionItem.vue
+++ b/frontend/src/components/modal/SuggestionItem.vue
@@ -8,6 +8,8 @@
       {{ suggestion.display_name }}
       <span v-if="suggestion.creates_new_tag" class="fc-suggestion__new"
         title="No matching tag yet — accepting creates it">+ new</span>
+      <span v-else-if="suggestion.via_alias" class="fc-suggestion__alias"
+        :title="`Mapped from the tagger's “${suggestion.raw_name}” via an alias`">alias</span>
     </span>
     <span class="fc-suggestion__score">{{ scorePct }}</span>
     <v-btn
@@ -25,9 +27,21 @@
       class="fc-suggestion__menu" size="small" variant="outlined"
       :label="`More actions for ${suggestion.display_name}`"
     >
-      <v-list-item @click="$emit('alias', suggestion)">
+      <!-- Alias is a tagger-prediction remap, so only offer it for tagger
+           suggestions with a raw model key that aren't already aliased.
+           Centroid hits (raw_name null) have nothing to alias. -->
+      <v-list-item
+        v-if="suggestion.raw_name && !suggestion.via_alias"
+        @click="$emit('alias', suggestion)"
+      >
         <v-list-item-title>Treat as alias for…</v-list-item-title>
       </v-list-item>
+      <v-list-item
+        v-if="suggestion.via_alias"
+        @click="$emit('remove-alias', suggestion)"
+      >
+        <v-list-item-title>Remove alias</v-list-item-title>
+      </v-list-item>
       <v-list-item @click="$emit('dismiss', suggestion)">
         <v-list-item-title>Dismiss for this image</v-list-item-title>
       </v-list-item>
@@ -40,7 +54,7 @@ import { computed } from 'vue'
 import KebabMenu from '../common/KebabMenu.vue'
 
 const props = defineProps({ suggestion: { type: Object, required: true } })
-defineEmits(['accept', 'alias', 'dismiss'])
+defineEmits(['accept', 'alias', 'remove-alias', 'dismiss'])
 
 const scorePct = computed(() => `${Math.round(props.suggestion.score * 100)}%`)
 </script>
@@ -74,6 +88,16 @@ const scorePct = computed(() => `${Math.round(props.suggestion.score * 100)}%`)
   margin-left: 6px;
   text-transform: uppercase; letter-spacing: 0.04em;
 }
+.fc-suggestion__alias {
+  display: inline-block;
+  font-size: 10px; font-weight: 600;
+  color: rgb(var(--v-theme-on-surface-variant));
+  background: rgb(var(--v-theme-surface-light));
+  border: 1px solid rgb(var(--v-theme-surface-light));
+  padding: 1px 6px; border-radius: 999px;
+  margin-left: 6px;
+  text-transform: uppercase; letter-spacing: 0.04em;
+}
 .fc-suggestion__score {
   flex: 0 0 auto; min-width: 38px; text-align: right;
   font-size: 11px;
diff --git a/frontend/src/components/modal/SuggestionsCategoryGroup.vue b/frontend/src/components/modal/SuggestionsCategoryGroup.vue
index c6c6611..c2b35bc 100644
--- a/frontend/src/components/modal/SuggestionsCategoryGroup.vue
+++ b/frontend/src/components/modal/SuggestionsCategoryGroup.vue
@@ -16,6 +16,7 @@
         :suggestion="s"
         @accept="$emit('accept', $event)"
         @alias="$emit('alias', $event)"
+        @remove-alias="$emit('remove-alias', $event)"
         @dismiss="$emit('dismiss', $event)"
       />
     </div>
@@ -32,7 +33,7 @@ const props = defineProps({
   collapsible: { type: Boolean, default: false },
   defaultOpen: { type: Boolean, default: true }
 })
-defineEmits(['accept', 'alias', 'dismiss'])
+defineEmits(['accept', 'alias', 'remove-alias', 'dismiss'])
 
 const open = ref(props.collapsible ? props.defaultOpen : true)
 </script>
diff --git a/frontend/src/components/modal/SuggestionsPanel.vue b/frontend/src/components/modal/SuggestionsPanel.vue
index 142d3f6..8b0ce45 100644
--- a/frontend/src/components/modal/SuggestionsPanel.vue
+++ b/frontend/src/components/modal/SuggestionsPanel.vue
@@ -17,13 +17,15 @@
         v-for="cat in peopleCats" :key="cat"
         v-show="store.byCategory[cat] && store.byCategory[cat].length"
         :label="labelFor(cat)" :items="store.byCategory[cat] || []"
-        @accept="onAccept" @alias="onAlias" @dismiss="store.dismiss"
+        @accept="onAccept" @alias="onAlias" @remove-alias="onRemoveAlias"
+        @dismiss="store.dismiss"
       />
       <SuggestionsCategoryGroup
         v-if="store.byCategory.general && store.byCategory.general.length"
         label="General" :items="store.byCategory.general"
         collapsible :default-open="true"
-        @accept="onAccept" @alias="onAlias" @dismiss="store.dismiss"
+        @accept="onAccept" @alias="onAlias" @remove-alias="onRemoveAlias"
+        @dismiss="store.dismiss"
       />
     </template>
 
@@ -98,6 +100,17 @@ async function onAliasConfirm(canonicalTagId) {
     toast({ text: `Alias failed: ${e.message}`, type: 'error' })
   }
 }
+
+// Undo the model-key→tag mapping behind an aliased suggestion. The store
+// reloads suggestions so the prediction reverts to its raw form; the applied
+// canonical tag (if any) stays, so no tag-rail reload is needed.
+async function onRemoveAlias(s) {
+  try {
+    await store.removeAlias(s)
+  } catch (e) {
+    toast({ text: `Remove alias failed: ${e.message}`, type: 'error' })
+  }
+}
 </script>
 
 <style scoped>
diff --git a/frontend/src/stores/suggestions.js b/frontend/src/stores/suggestions.js
index 4209570..344b1f5 100644
--- a/frontend/src/stores/suggestions.js
+++ b/frontend/src/stores/suggestions.js
@@ -117,9 +117,15 @@ export const useSuggestionsStore = defineStore('suggestions', () => {
   async function aliasAccept(suggestion, canonicalTagId) {
     const imageId = currentImageId
     if (imageId == null) return
+    // The alias MUST be stored under the raw model key — resolution looks up the
+    // raw prediction key, not the normalized display name. Sending display_name
+    // (the old bug) stored an alias that never resolved, so the prediction kept
+    // reappearing unaliased. raw_name is null only for centroid hits, which
+    // can't be aliased (the UI hides the action for them).
+    const aliasString = suggestion.raw_name ?? suggestion.display_name
     await api.post(`/api/images/${imageId}/suggestions/alias`, {
       body: {
-        alias_string: suggestion.display_name,
+        alias_string: aliasString,
         alias_category: suggestion.category,
         canonical_tag_id: canonicalTagId
       }
@@ -133,6 +139,22 @@ export const useSuggestionsStore = defineStore('suggestions', () => {
     })
   }
 
+  // Remove the alias behind an aliased suggestion (the raw prediction reverts to
+  // its unaliased form on reload). The canonical tag stays applied if it was
+  // accepted — this only undoes the model-key→tag mapping.
+  async function removeAlias(suggestion) {
+    const imageId = currentImageId
+    if (imageId == null || suggestion.raw_name == null) return
+    await api.delete(
+      `/api/aliases/${encodeURIComponent(suggestion.raw_name)}/${encodeURIComponent(suggestion.category)}`
+    )
+    if (currentImageId === imageId) {
+      await load(imageId)
+      await loadAll(imageId)
+    }
+    toast({ text: `Alias removed: ${suggestion.display_name}`, type: 'success' })
+  }
+
   async function dismiss(suggestion) {
     const imageId = currentImageId
     if (imageId == null) return
@@ -151,6 +173,6 @@ export const useSuggestionsStore = defineStore('suggestions', () => {
 
   return {
     byCategory, allByCategory, loading, error,
-    load, loadAll, accept, aliasAccept, dismiss
+    load, loadAll, accept, aliasAccept, removeAlias, dismiss
   }
 })
diff --git a/frontend/src/views/TagsView.vue b/frontend/src/views/TagsView.vue
index c97925f..1bbae8b 100644
--- a/frontend/src/views/TagsView.vue
+++ b/frontend/src/views/TagsView.vue
@@ -25,7 +25,7 @@
         v-for="c in store.cards" :key="c.id" :card="c"
         @open="openTag" @rename="onRename" @manage="onManage" @read="onRead"
         @merge-with="onMergeWith" @delete="onDeleteTag"
-        @set-fandom="onSetFandom"
+        @set-fandom="onSetFandom" @aliases="onAliases"
       />
     </div>
 
@@ -96,6 +96,13 @@
         @updated="onFandomUpdated" @cancel="fandomDialogOpen = false"
       />
     </v-dialog>
+
+    <v-dialog v-model="aliasesDialogOpen" max-width="480">
+      <TagAliasesDialog
+        v-if="aliasesTarget" :tag="aliasesTarget"
+        @close="aliasesDialogOpen = false"
+      />
+    </v-dialog>
   </v-container>
 </template>
 
@@ -111,6 +118,7 @@ import TagCard from '../components/discovery/TagCard.vue'
 import MergeConfirmDialog from '../components/discovery/MergeConfirmDialog.vue'
 import DestructiveConfirmModal from '../components/modal/DestructiveConfirmModal.vue'
 import FandomSetDialog from '../components/modal/FandomSetDialog.vue'
+import TagAliasesDialog from '../components/discovery/TagAliasesDialog.vue'
 
 // Must stay a subset of the backend TagKind enum (character, fandom,
 // general, series, archive, post). 'fandom' is this model's
@@ -165,6 +173,15 @@ function onFandomUpdated() {
   store.reset()  // reload so the card reflects the new fandom (or its removal)
 }
 
+// Tag-side alias view (TagCard ⋮ → Aliases…): see/remove the model keys that
+// fold into this tag. Creation lives in the image modal's suggestion flow.
+const aliasesDialogOpen = ref(false)
+const aliasesTarget = ref(null)
+function onAliases(card) {
+  aliasesTarget.value = card
+  aliasesDialogOpen.value = true
+}
+
 function onManage(id) {
   router.push({ name: 'series-manage', params: { tagId: id } })
 }
diff --git a/tests/test_api_aliases.py b/tests/test_api_aliases.py
index 103b75e..09860cd 100644
--- a/tests/test_api_aliases.py
+++ b/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
diff --git a/tests/test_api_suggestions.py b/tests/test_api_suggestions.py
index b9fd041..84b95b0 100644
--- a/tests/test_api_suggestions.py
+++ b/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"
diff --git a/tests/test_ml_aliases.py b/tests/test_ml_aliases.py
index 2253b73..aa957c3 100644
--- a/tests/test_ml_aliases.py
+++ b/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)
diff --git a/tests/test_ml_suggestions.py b/tests/test_ml_suggestions.py
index 891b54f..3f532bd 100644
--- a/tests/test_ml_suggestions.py
+++ b/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