internal/library/delete.go

@@ -29,9 +29,12 @@ var ErrTrackNotFound = errors.New("library: track not found")
 //
 // Order matters: file first, then DB. If the file delete fails (permission,
 // I/O error), we leave the DB row alone so the admin can retry. The reverse
-// failure mode — file gone, DB row still present — is recoverable: the next
-// library scan reconciles missing files by removing their tracks rows. So
-// the function is retry-safe rather than atomic, by design.
+// failure mode — file gone, DB row still present — is currently NOT
+// auto-reconciled (drift #572 audit found the misleading prior claim
+// that a scan would clean it up — the scanner only walks + upserts;
+// it does not enumerate orphan rows). An admin must re-trigger
+// DeleteTrackFile or delete the row manually. A scanrun orphan-row
+// sweep is tracked as future work in the audit queue.
 func DeleteTrackFile(ctx context.Context, pool *pgxpool.Pool, trackID pgtype.UUID) error {
 	q := dbq.New(pool)
 	track, err := q.GetTrackByID(ctx, trackID)