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>

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>

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)

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;

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>

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>

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
   }
 })

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 } })
 }