feat(collections): merge archived duplicates into their active copy

Covers the copy-then-delete-later workflow: a user copies books to a new
library, deletes the originals, and ends up with an active copy in the new
library plus an archived twin holding the real reading history. Until now
those twins could only be purged (destroying the history) or restored
(showing a permanently broken entry).

- POST /api/media-items/:id/merge (admin only, body {target_id}):
  validates the source is archived/missing, the target is active, and
  both share the same file_sha256; then re-parents every child row onto
  the target via the existing reparent_media_item_children function (the
  same machinery as hash-conflict resolution) and deletes the source row.
  Per-user collisions keep the active copy's data, mirroring that flow.
  Affected data: reading progress, speed, ratings, highlights, notes,
  bookmarks (including tombstoned deleted-annotation history), formats,
  collections, kobo shelves/entitlements, sync rows, panel data,
  processing issues, and device aliases.
- GET /admin/archived: ListHiddenMediaItems' match_* columns surface each
  row's best active twin; rows with a twin get a confirm-guarded "Merge"
  button (data-merge-source/-target) next to Restore/Delete, wired in
  web/src/admin.ts like the existing unarchive/delete handlers.
- templates.ArchivedItem gains MatchID/MatchTitle/MatchLibraryName;
  frontend.go populates them from the listing row.

After a merge the archived row is gone, so the retention purge can never
destroy the merged data. Deleted-annotation tombstones carry over and
remain restorable from the target book's "recently deleted" history.

internal/handlers/media.go

@@ -1354,6 +1354,83 @@ func (mh *MediaHandler) UnarchiveMediaItem(c *echo.Context) error {
 	return c.NoContent(http.StatusNoContent)
 }
 
+// MergeArchivedMediaItem handles POST /api/media-items/:id/merge (admin
+// only). Merges an archived/missing item's reading data (progress,
+// annotations, highlights, notes, bookmarks, ratings, collections, kobo
+// shelves) into an active item with identical content (same SHA-256), then
+// deletes the archived row. Covers the copy-then-delete-later workflow: the
+// active copy exists, the archived twin holds the real reading history.
+// Per-user collisions keep the active copy's data, mirroring hash-conflict
+// resolution.
+func (mh *MediaHandler) MergeArchivedMediaItem(c *echo.Context) error {
+	user := MustGetAuthenticatedUser(c)
+
+	if user.Role != "admin" {
+		return c.JSON(http.StatusForbidden, map[string]string{"error": "admin access required"})
+	}
+
+	sourceUUID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid media item id"})
+	}
+
+	var req struct {
+		TargetID string `json:"target_id"`
+	}
+	if err := c.Bind(&req); err != nil || req.TargetID == "" {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "target_id is required"})
+	}
+	targetUUID, err := uuid.Parse(req.TargetID)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid target_id"})
+	}
+	if sourceUUID == targetUUID {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "cannot merge an item into itself"})
+	}
+
+	ctx := c.Request().Context()
+	source, err := mh.db.GetMediaItem(ctx, pgtype.UUID{Bytes: sourceUUID, Valid: true})
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return c.JSON(http.StatusNotFound, map[string]string{"error": "archived item not found"})
+		}
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+	if !source.ArchivedAt.Valid && source.MissingScanCount == 0 {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "source item is not archived or missing"})
+	}
+
+	target, err := mh.db.GetMediaItem(ctx, pgtype.UUID{Bytes: targetUUID, Valid: true})
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return c.JSON(http.StatusNotFound, map[string]string{"error": "target item not found"})
+		}
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+	if target.ArchivedAt.Valid || target.MissingScanCount > 0 {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "target item is not active"})
+	}
+
+	if !source.FileSha256.Valid || source.FileSha256.String == "" ||
+		source.FileSha256.String != target.FileSha256.String {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "items do not share the same content hash"})
+	}
+
+	if err := mh.db.ReparentMediaItemChildren(ctx, database.ReparentMediaItemChildrenParams{
+		Column1: pgtype.UUID{Bytes: targetUUID, Valid: true},
+		Column2: pgtype.UUID{Bytes: sourceUUID, Valid: true},
+	}); err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "failed to merge reading data: " + err.Error()})
+	}
+	if err := mh.db.DeleteMediaItem(ctx, pgtype.UUID{Bytes: sourceUUID, Valid: true}); err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "failed to remove archived item: " + err.Error()})
+	}
+
+	return c.JSON(http.StatusOK, map[string]string{
+		"message": "Merged reading progress, annotations, and collections into the active item",
+	})
+}
+
 // PurgeArchivedMediaItems handles POST /api/media-items/purge-archived
 // (admin only). Hard-deletes every archived item (files missing from disk for
 // 2+ scans) together with its reading history. The archive retention window

internal/router/frontend.go

@@ -873,6 +873,11 @@ func registerFrontendRoutes(cfg *Config) {
 				FilePath:     row.FilePath,
 				MissingScans: row.MissingScanCount,
 			}
+			if row.MatchID.Valid {
+				item.MatchID = uuid.UUID(row.MatchID.Bytes).String()
+				item.MatchTitle = row.MatchTitle
+				item.MatchLibraryName = getText(row.MatchLibraryName)
+			}
 			if row.ArchivedAt.Valid {
 				archived := row.ArchivedAt.Time
 				item.ArchivedAt = &archived

internal/router/media.go

@@ -64,6 +64,7 @@ func registerMediaRoutes(cfg *Config) {
 	admin.DELETE("/media-items/:id", cfg.MediaHandler.DeleteMediaItem)
 	admin.POST("/media-items/purge-archived", cfg.MediaHandler.PurgeArchivedMediaItems)
 	admin.POST("/media-items/:id/unarchive", cfg.MediaHandler.UnarchiveMediaItem)
+	admin.POST("/media-items/:id/merge", cfg.MediaHandler.MergeArchivedMediaItem)
 
 	// Shelf management (protected)
 	protected.POST("/devices/:id/shelves", cfg.MediaHandler.AddToShelf)

templates/admin_archived.templ

@@ -71,6 +71,18 @@ templ AdminArchived(user User, items []ArchivedItem, retentionDays int) {
 											<td class="px-4 py-3" style="color: var(--text-primary)">{ item.LibraryName }</td>
 											<td class="px-4 py-3" style="color: var(--text-secondary)">{ item.Status }</td>
 											<td class="px-4 py-3 text-right whitespace-nowrap">
+												if item.MatchID != "" {
+													<button
+														type="button"
+														data-merge-source={ item.ID }
+														data-merge-target={ item.MatchID }
+														class="btn btn-ghost text-xs"
+														title={ "Merge this archived copy's reading data into the active copy \"" + item.MatchTitle + "\" (" + item.MatchLibraryName + ") and remove the archived entry" }
+													>
+														@Icon("copy", "h-3.5 w-3.5")
+														Merge
+													</button>
+												}
 												<button
 													type="button"
 													data-unarchive={ item.ID }

templates/admin_archived_templ.go

@@ -57,7 +57,7 @@ func AdminArchived(user User, items []ArchivedItem, retentionDays int) templ.Com
 			var templ_7745c5c3_Var2 string
 			templ_7745c5c3_Var2, templ_7745c5c3_Err = templ.JoinStringErrs(retentionDays)
 			if templ_7745c5c3_Err != nil {
-				return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 30, Col: 70}
+				return templ.Error{Err: templ_7745c5c3_Err, FileName: `admin_archived.templ`, Line: 30, Col: 70}
 			}
 			_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var2))
 			if templ_7745c5c3_Err != nil {
@@ -113,7 +113,7 @@ func AdminArchived(user User, items []ArchivedItem, retentionDays int) templ.Com
 				var templ_7745c5c3_Var3 string
 				templ_7745c5c3_Var3, templ_7745c5c3_Err = templ.JoinStringErrs(item.Title)
 				if templ_7745c5c3_Err != nil {
-					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 65, Col: 82}
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `admin_archived.templ`, Line: 65, Col: 82}
 				}
 				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var3))
 				if templ_7745c5c3_Err != nil {
@@ -131,7 +131,7 @@ func AdminArchived(user User, items []ArchivedItem, retentionDays int) templ.Com
 					var templ_7745c5c3_Var4 string
 					templ_7745c5c3_Var4, templ_7745c5c3_Err = templ.JoinStringErrs(item.Author)
 					if templ_7745c5c3_Err != nil {
-						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 67, Col: 66}
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `admin_archived.templ`, Line: 67, Col: 66}
 					}
 					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var4))
 					if templ_7745c5c3_Err != nil {
@@ -149,7 +149,7 @@ func AdminArchived(user User, items []ArchivedItem, retentionDays int) templ.Com
 				var templ_7745c5c3_Var5 string
 				templ_7745c5c3_Var5, templ_7745c5c3_Err = templ.JoinStringErrs(item.FilePath)
 				if templ_7745c5c3_Err != nil {
-					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 69, Col: 103}
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `admin_archived.templ`, Line: 69, Col: 103}
 				}
 				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var5))
 				if templ_7745c5c3_Err != nil {
@@ -162,7 +162,7 @@ func AdminArchived(user User, items []ArchivedItem, retentionDays int) templ.Com
 				var templ_7745c5c3_Var6 string
 				templ_7745c5c3_Var6, templ_7745c5c3_Err = templ.JoinStringErrs(item.LibraryName)
 				if templ_7745c5c3_Err != nil {
-					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 71, Col: 86}
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `admin_archived.templ`, Line: 71, Col: 86}
 				}
 				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var6))
 				if templ_7745c5c3_Err != nil {
@@ -175,26 +175,83 @@ func AdminArchived(user User, items []ArchivedItem, retentionDays int) templ.Com
 				var templ_7745c5c3_Var7 string
 				templ_7745c5c3_Var7, templ_7745c5c3_Err = templ.JoinStringErrs(item.Status)
 				if templ_7745c5c3_Err != nil {
-					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 72, Col: 83}
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `admin_archived.templ`, Line: 72, Col: 83}
 				}
 				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var7))
 				if templ_7745c5c3_Err != nil {
 					return templ_7745c5c3_Err
 				}
-				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 20, "</td><td class=\"px-4 py-3 text-right whitespace-nowrap\"><button type=\"button\" data-unarchive=\"")
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 20, "</td><td class=\"px-4 py-3 text-right whitespace-nowrap\">")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				if item.MatchID != "" {
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 21, "<button type=\"button\" data-merge-source=\"")
 					if templ_7745c5c3_Err != nil {
 						return templ_7745c5c3_Err
 					}
 					var templ_7745c5c3_Var8 string
 					templ_7745c5c3_Var8, templ_7745c5c3_Err = templ.ResolveAttributeValue(item.ID)
 					if templ_7745c5c3_Err != nil {
-					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 76, Col: 37}
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `admin_archived.templ`, Line: 77, Col: 41}
 					}
 					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var8)
 					if templ_7745c5c3_Err != nil {
 						return templ_7745c5c3_Err
 					}
-				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 21, "\" class=\"btn btn-ghost text-xs\" title=\"Restore to libraries now; if the file is still gone the next scan hides it again\">")
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 22, "\" data-merge-target=\"")
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					var templ_7745c5c3_Var9 string
+					templ_7745c5c3_Var9, templ_7745c5c3_Err = templ.ResolveAttributeValue(item.MatchID)
+					if templ_7745c5c3_Err != nil {
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `admin_archived.templ`, Line: 78, Col: 46}
+					}
+					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var9)
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 23, "\" class=\"btn btn-ghost text-xs\" title=\"")
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					var templ_7745c5c3_Var10 string
+					templ_7745c5c3_Var10, templ_7745c5c3_Err = templ.ResolveAttributeValue("Merge this archived copy's reading data into the active copy \"" + item.MatchTitle + "\" (" + item.MatchLibraryName + ") and remove the archived entry")
+					if templ_7745c5c3_Err != nil {
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `admin_archived.templ`, Line: 80, Col: 174}
+					}
+					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var10)
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 24, "\">")
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					templ_7745c5c3_Err = Icon("copy", "h-3.5 w-3.5").Render(ctx, templ_7745c5c3_Buffer)
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 25, "Merge</button> ")
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 26, "<button type=\"button\" data-unarchive=\"")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				var templ_7745c5c3_Var11 string
+				templ_7745c5c3_Var11, templ_7745c5c3_Err = templ.ResolveAttributeValue(item.ID)
+				if templ_7745c5c3_Err != nil {
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `admin_archived.templ`, Line: 88, Col: 37}
+				}
+				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var11)
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 27, "\" class=\"btn btn-ghost text-xs\" title=\"Restore to libraries now; if the file is still gone the next scan hides it again\">")
 				if templ_7745c5c3_Err != nil {
 					return templ_7745c5c3_Err
 				}
@@ -202,20 +259,20 @@ func AdminArchived(user User, items []ArchivedItem, retentionDays int) templ.Com
 				if templ_7745c5c3_Err != nil {
 					return templ_7745c5c3_Err
 				}
-				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 22, "Restore</button> <button type=\"button\" data-delete-archived=\"")
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 28, "Restore</button> <button type=\"button\" data-delete-archived=\"")
 				if templ_7745c5c3_Err != nil {
 					return templ_7745c5c3_Err
 				}
-				var templ_7745c5c3_Var9 string
-				templ_7745c5c3_Var9, templ_7745c5c3_Err = templ.ResolveAttributeValue(item.ID)
+				var templ_7745c5c3_Var12 string
+				templ_7745c5c3_Var12, templ_7745c5c3_Err = templ.ResolveAttributeValue(item.ID)
 				if templ_7745c5c3_Err != nil {
-					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 85, Col: 43}
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `admin_archived.templ`, Line: 97, Col: 43}
 				}
-				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var9)
+				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var12)
 				if templ_7745c5c3_Err != nil {
 					return templ_7745c5c3_Err
 				}
-				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 23, "\" class=\"btn btn-ghost text-xs\" title=\"Delete this item and its reading history permanently\">")
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 29, "\" class=\"btn btn-ghost text-xs\" title=\"Delete this item and its reading history permanently\">")
 				if templ_7745c5c3_Err != nil {
 					return templ_7745c5c3_Err
 				}
@@ -223,17 +280,17 @@ func AdminArchived(user User, items []ArchivedItem, retentionDays int) templ.Com
 				if templ_7745c5c3_Err != nil {
 					return templ_7745c5c3_Err
 				}
-				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 24, "Delete</button></td></tr>")
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 30, "Delete</button></td></tr>")
 				if templ_7745c5c3_Err != nil {
 					return templ_7745c5c3_Err
 				}
 			}
-			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 25, "</tbody></table></div>")
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 31, "</tbody></table></div>")
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
 		}
-		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 26, "</div></main></body></html>")
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 32, "</div></main></body></html>")
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}

templates/types.go

@@ -52,7 +52,10 @@ type FolderData struct {
 }
 
 // ArchivedItem feeds the admin archived-items page: media hidden from
-// libraries because their files vanished, with their pending fate.
+// libraries because their files vanished, with their pending fate. When an
+// active item with identical content (same SHA-256) exists, MatchID and
+// friends are set so the UI can offer merging the archived row's reading
+// data into its active twin.
 type ArchivedItem struct {
 	ID               string
 	Title            string
@@ -63,6 +66,9 @@ type ArchivedItem struct {
 	ArchivedAt       *time.Time
 	PurgeAt          *time.Time
 	Status           string
+	MatchID          string
+	MatchTitle       string
+	MatchLibraryName string
 }
 
 type DirEntry struct {

web/src/admin.ts

@@ -339,6 +339,39 @@ async function deleteArchivedItem(id: string): Promise<void> {
   }
 }
 
+// Merge an archived item's reading data into its active duplicate with the
+// same content hash (POST /api/media-items/:id/merge), then remove the
+// archived entry. Covers copy-then-delete-later moves between libraries.
+async function mergeArchivedItem(sourceId: string, targetId: string): Promise<void> {
+  const token = localStorage.getItem("token");
+  if (!token) return;
+  if (
+    !window.confirm(
+      "Merge this archived copy's reading progress, notes, and highlights into the active copy? The archived entry is removed.",
+    )
+  ) {
+    return;
+  }
+  try {
+    const resp = await fetch(`/api/media-items/${sourceId}/merge`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ target_id: targetId }),
+    });
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({}));
+      throw new Error(err.error || "Failed to merge item");
+    }
+    showToast("Reading data merged into active copy", "success");
+    setTimeout(() => window.location.reload(), 500);
+  } catch (e) {
+    showToast(e instanceof Error ? e.message : "Failed to merge item", "error");
+  }
+}
+
 // The archived-items page renders per-row buttons with data attributes
 // (escaping-safe); bind them here. Module scripts run after DOM parse.
 document.querySelectorAll<HTMLElement>("[data-unarchive]").forEach((el) => {
@@ -349,6 +382,11 @@ document.querySelectorAll<HTMLElement>("[data-delete-archived]").forEach((el) =>
     deleteArchivedItem(el.dataset.deleteArchived || ""),
   );
 });
+document.querySelectorAll<HTMLElement>("[data-merge-source]").forEach((el) => {
+  el.addEventListener("click", () =>
+    mergeArchivedItem(el.dataset.mergeSource || "", el.dataset.mergeTarget || ""),
+  );
+});
 
 export {
   hideScanProgress,