fix: use top-K quality faces for fallback attach scoring to prevent person splits

When a face component's average score falls below the attach threshold due to
low-quality faces (blurry, side-angle) dragging down the average, re-score using
only the top-5 highest-quality faces. This prevents creating duplicate persons
for the same individual when high-quality faces clearly match an existing person.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: davidhoo

backend/internal/service/people_service.go

@@ -41,6 +41,10 @@ const (
 	// making it easier for new faces to join user-confirmed identities (e.g., family members).
 	confirmedPersonDiscount = 0.05
 
+	// attachTopK is the number of highest-quality faces used for fallback scoring
+	// when the full-component average falls below the attach threshold.
+	attachTopK = 5
+
 	// Adaptive threshold decay for long-pending faces
 	// retry_count 0-1: full threshold (no discount)
 	// retry_count 2-4: linear decay to floor
@@ -2109,6 +2113,27 @@ func (s *peopleService) scoreComponentAgainstPersonWithEmbeddings(component []fa
 	return total / float64(scored)
 }
 
+// topKFacesByQuality returns the k faces with the highest QualityScore from the component.
+func topKFacesByQuality(component []faceWithEmbedding, k int) []faceWithEmbedding {
+	if len(component) <= k {
+		return component
+	}
+	sorted := make([]faceWithEmbedding, len(component))
+	copy(sorted, component)
+	sort.Slice(sorted, func(i, j int) bool {
+		qi := 0.0
+		if sorted[i].face != nil {
+			qi = sorted[i].face.QualityScore
+		}
+		qj := 0.0
+		if sorted[j].face != nil {
+			qj = sorted[j].face.QualityScore
+		}
+		return qi > qj
+	})
+	return sorted[:k]
+}
+
 func (s *peopleService) attachComponentToExistingPerson(component []*model.Face, prototypes map[uint][]*model.Face, attachThreshold float64) (uint, float64, bool) {
 	if len(component) == 0 || len(prototypes) == 0 {
 		return 0, -1, false
@@ -2195,6 +2220,18 @@ func (s *peopleService) attachComponentToExistingPersonWithEmbeddings(
 		return bestPersonID, bestScore, true
 	}
 
+	// Fallback: re-score using only the top-K highest-quality faces in the component.
+	// Low-quality faces (blurry, side-angle) drag down the average score, causing
+	// splits where a component should have attached to an existing person.
+	// If the top-K faces score above the threshold, attach anyway.
+	if bestPersonID != 0 && len(component) > attachTopK {
+		topK := topKFacesByQuality(component, attachTopK)
+		topKScore := s.scoreComponentAgainstPersonWithEmbeddings(topK, prototypesWithEmb[bestPersonID])
+		if topKScore >= attachThreshold {
+			return bestPersonID, topKScore, true
+		}
+	}
+
 	// Apply discount for confirmed persons (have manual-locked faces)
 	if bestPersonID != 0 && bestScore >= attachThreshold-confirmedPersonDiscount {
 		for _, proto := range prototypesOriginal[bestPersonID] {

backend/internal/service/people_service_test.go

@@ -369,6 +369,32 @@ func TestPeopleService_AttachComponentToExistingPerson(t *testing.T) {
 		assert.Zero(t, personID)
 		assert.Less(t, attachScore, 0.70) // defaultAttachThreshold
 	})
+
+	t.Run("component attaches via top-K fallback when low-quality faces drag down average", func(t *testing.T) {
+		// 5 high-quality faces close to personOne's prototypes, plus 5 low-quality orthogonal faces.
+		// The full-component average falls below threshold, but top-5 quality faces should pass.
+		component := []*model.Face{
+			{ID: 100, QualityScore: 0.9, Embedding: encodeEmbedding(t, []float32{1, 0, 0})},
+			{ID: 101, QualityScore: 0.85, Embedding: encodeEmbedding(t, []float32{0.98, 0.199, 0})},
+			{ID: 102, QualityScore: 0.80, Embedding: encodeEmbedding(t, []float32{0.97, 0.243, 0})},
+			{ID: 103, QualityScore: 0.75, Embedding: encodeEmbedding(t, []float32{0.99, 0.1, 0})},
+			{ID: 104, QualityScore: 0.70, Embedding: encodeEmbedding(t, []float32{0.96, 0.28, 0})},
+			// Low-quality orthogonal faces (drag down average)
+			{ID: 200, QualityScore: 0.1, Embedding: encodeEmbedding(t, []float32{0, 0, 1})},
+			{ID: 201, QualityScore: 0.1, Embedding: encodeEmbedding(t, []float32{0.05, 0.05, 0.99})},
+			{ID: 202, QualityScore: 0.1, Embedding: encodeEmbedding(t, []float32{0.02, 0.02, 0.999})},
+			{ID: 203, QualityScore: 0.1, Embedding: encodeEmbedding(t, []float32{0, 0.1, 0.995})},
+			{ID: 204, QualityScore: 0.1, Embedding: encodeEmbedding(t, []float32{0.03, 0, 0.999})},
+		}
+
+		fullScore := attacher.scoreComponentAgainstPerson(component, prototypes[personOneID])
+		assert.Less(t, fullScore, 0.70, "full component score should be below threshold due to low-quality faces")
+
+		personID, attachScore, attached := attacher.attachComponentToExistingPerson(component, prototypes, 0.70)
+		assert.True(t, attached, "should attach via top-K fallback")
+		assert.Equal(t, personOneID, personID)
+		assert.GreaterOrEqual(t, attachScore, 0.70)
+	})
 }
 
 func TestPeopleService_PendingComponent(t *testing.T) {