Faces: Rename the embed_upscaled column to embed_detail

The value is the share of the crop its source supplied, so 100 means the crop
was not upscaled - which made embed_upscaled read backwards at the one value
worth a clean predicate. The three names now agree: face.EmbedDetail computes
it, SetEmbedDetail writes it, embed_detail stores it. The embed_ prefix stands
for the reason it always did, that the column describes the embedding rather
than the thumbnail its partner thumb_size names.

No shim and no rename migration: nothing has shipped the old column, so
AutoMigrate creating embed_detail is the whole change. A local database that
saw the old name keeps a stale column until it is dropped by hand.

Author: lastzero

internal/ai/face/README.md

@@ -116,7 +116,7 @@ The on-demand size limit is lifted for the duration of the run (`useMigrationThu
 
 Two consequences worth knowing. A warped crop is not interchangeable with a `crop.Sizes` tile, so 112 cannot simply join that table - though a 112 *rectangle* would render as well as `Tile100` if the UI ever wants one. And because the smallest face selects the rendition for the whole file, one tiny face makes every other face in it decode a larger image; that is the lever to measure if embedding cost ever matters, not a crop cache.
 
-**`markers.embed_upscaled` says how much of the crop the source supplied**, beside the extent in `thumb_size` that supplied it: 100 is full detail, 1 to 99 says the crop was interpolated and by how much, `EmbedUpscaledUnknown` is a migration that sampled the marker without measuring a ratio, and -1 a marker nothing has sampled. The two columns are written under one condition, so a marker embedded through an endpoint - a reused crop, which reports no source width - records neither rather than one of each. ⚠ The denominator is the crop the embedder was handed, which is the model's 112 px template for an aligned crop and the 160 px `face.CropSize` box for the fallback, so a distribution over the column mixes two scales. It is measured where the crop is taken rather than derived afterwards, because `face.CropSize` and a model's input geometry describe what is configured now and not the vector that was produced. Only the two paths that produce an embedding write it, as with `thumb_size`, and no command synthesizes it. There is deliberately no per-marker warning for an upscaled crop: a default install puts a double-digit percentage of markers in that bucket, so the distribution answers whether it matters and a line each does not.
+**`markers.embed_detail` says how much of the crop the source supplied**, beside the extent in `thumb_size` that supplied it: 100 is full detail, 1 to 99 says the crop was interpolated and by how much, `EmbedDetailUnknown` is a migration that sampled the marker without measuring a ratio, and -1 a marker nothing has sampled. The two columns are written under one condition, so a marker embedded through an endpoint - a reused crop, which reports no source width - records neither rather than one of each. ⚠ The denominator is the crop the embedder was handed, which is the model's 112 px template for an aligned crop and the 160 px `face.CropSize` box for the fallback, so a distribution over the column mixes two scales. It is measured where the crop is taken rather than derived afterwards, because `face.CropSize` and a model's input geometry describe what is configured now and not the vector that was produced. Only the two paths that produce an embedding write it, as with `thumb_size`, and no command synthesizes it. There is deliberately no per-marker warning for an upscaled crop: a default install puts a double-digit percentage of markers in that bucket, so the distribution answers whether it matters and a line each does not.
 
 **A marker is stale when its vector, its crop, or its sample extent is.** The first two make it stale because it is in the wrong space; the third because nothing can judge what the vector rests on until the crop is sampled again, and only a re-embedding measures it. Without the third condition a library **already on the target model** is skipped whole - on one reference instance 88,353 of 89,516 markers - which leaves `thumb_size` unset and `FACE_CLUSTER_SIZE` falling back to the detection size the column was added to replace. It is a staleness condition rather than a `--repair` flag for that reason: an opt-in switch reproduces the failure it fixes, a gap nobody knows to close, and `--dry-run` already prices the work before it is paid for. The honest cost is that a re-run against an already-migrated library now has real work to do, once - `entity.ThumbSizeUnmeasured` records a sampling that reached a marker and measured nothing, whether the vector was regenerated or not, which is what makes it once rather than every run. A file that could not be read is left unsettled, because that fault may clear.
 

internal/ai/face/cluster_size_test.go

@@ -86,32 +86,32 @@ func TestEmbedDetail(t *testing.T) {
 	})
 }
 
-// TestFace_SetEmbedUpscaled covers the detail recorded beside an embedding, which is measured at
+// TestFace_SetEmbedDetail covers the detail recorded beside an embedding, which is measured at
 // the crop rather than derived afterwards from a template that may since have changed.
-func TestFace_SetEmbedUpscaled(t *testing.T) {
+func TestFace_SetEmbedDetail(t *testing.T) {
 	t.Run("AlignedTemplate", func(t *testing.T) {
 		f := &Face{Cols: 720, Area: Area{Scale: 60}}
 		f.SetThumbSize(720)
-		f.SetEmbedUpscaled(ArcFaceTemplateSize)
+		f.SetEmbedDetail(ArcFaceTemplateSize)
 
 		assert.Equal(t, 60, f.ThumbSize)
-		assert.Equal(t, 54, f.EmbedUpscaled)
+		assert.Equal(t, 54, f.EmbedDetail)
 	})
 	t.Run("WiderRenditionRemovesTheUpscale", func(t *testing.T) {
 		// The same face embedded from a 1920 px rendition instead of the detection thumbnail.
 		f := &Face{Cols: 720, Area: Area{Scale: 60}}
 		f.SetThumbSize(1920)
-		f.SetEmbedUpscaled(ArcFaceTemplateSize)
+		f.SetEmbedDetail(ArcFaceTemplateSize)
 
-		assert.Equal(t, 100, f.EmbedUpscaled)
+		assert.Equal(t, 100, f.EmbedDetail)
 	})
 	t.Run("UnsampledLeavesItUnset", func(t *testing.T) {
 		f := &Face{Cols: 720, Area: Area{Scale: 60}}
-		f.SetEmbedUpscaled(ArcFaceTemplateSize)
+		f.SetEmbedDetail(ArcFaceTemplateSize)
 
-		assert.Zero(t, f.EmbedUpscaled, "no extent was recorded to measure against")
+		assert.Zero(t, f.EmbedDetail, "no extent was recorded to measure against")
 	})
 	t.Run("Nil", func(t *testing.T) {
-		assert.NotPanics(t, func() { (*Face)(nil).SetEmbedUpscaled(112) })
+		assert.NotPanics(t, func() { (*Face)(nil).SetEmbedDetail(112) })
 	})
 }

internal/ai/face/face.go

@@ -48,9 +48,9 @@ type Face struct {
 	// ThumbSize is the face's extent in pixels of the thumbnail its embedding was sampled from,
 	// which is a different image than Size measures. Zero until an embedding is generated.
 	ThumbSize int `json:"thumbSize,omitempty"`
-	// EmbedUpscaled is the percentage of the crop width the source supplied, clamped at 100, so
+	// EmbedDetail is the percentage of the crop width the source supplied, clamped at 100, so
 	// a value below it says the crop was upscaled and by how much. Zero until measured.
-	EmbedUpscaled int `json:"embedUpscaled,omitempty"`
+	EmbedDetail int `json:"embedDetail,omitempty"`
 }
 
 // SetThumbSize records the face's extent in an image of the given width, which is what the
@@ -79,18 +79,18 @@ func EmbedDetail(extent, cropWidth int) int {
 	return min(100, max(1, int(math.Round(float64(extent)*100/float64(cropWidth)))))
 }
 
-// SetEmbedUpscaled records how much of the crop the embedder asked for the source could supply.
+// SetEmbedDetail records how much of the crop the embedder asked for the source could supply.
 // It is measured here rather than derived later, because face.CropSize is a property of the
 // current template and not of the vector that was produced.
 //
 // SetThumbSize has to have run first: it holds the face's extent in the image the crop was taken
 // from, which is the numerator. An unmeasurable ratio is left unset, so no guess is stored.
-func (f *Face) SetEmbedUpscaled(cropWidth int) {
+func (f *Face) SetEmbedDetail(cropWidth int) {
 	if f == nil {
 		return
 	}
 
-	f.EmbedUpscaled = EmbedDetail(f.ThumbSize, cropWidth)
+	f.EmbedDetail = EmbedDetail(f.ThumbSize, cropWidth)
 }
 
 // Size returns the absolute face size in pixels.

internal/ai/vision/embeddings.go

@@ -58,9 +58,9 @@ func GenerateEmbeddings(embedder face.Embedder, fileName string, faces face.Face
 			// The crop the embedder was handed: an aligned model warps the landmarks onto its
 			// own input, and the fallback resamples a face.CropSize box.
 			if aligned {
-				f.SetEmbedUpscaled(width)
+				f.SetEmbedDetail(width)
 			} else {
-				f.SetEmbedUpscaled(face.CropSize.Width)
+				f.SetEmbedDetail(face.CropSize.Width)
 			}
 
 			// Counted here rather than at the crop, since a crop nothing was embedded from

internal/ai/vision/embeddings_test.go

@@ -113,7 +113,7 @@ func TestGenerateEmbeddings(t *testing.T) {
 
 		require.False(t, faces[0].Embeddings.Empty())
 		assert.Equal(t, 284, faces[0].ThumbSize)
-		assert.Equal(t, 100, faces[0].EmbedUpscaled)
+		assert.Equal(t, 100, faces[0].EmbedDetail)
 	})
 	t.Run("RecordsTheShortfallOfASmallFace", func(t *testing.T) {
 		// The same picture and a 40 px face, which covers 57 px of it: the crop the model reads
@@ -124,7 +124,7 @@ func TestGenerateEmbeddings(t *testing.T) {
 
 		require.False(t, faces[0].Embeddings.Empty())
 		assert.Equal(t, 57, faces[0].ThumbSize)
-		assert.Equal(t, 51, faces[0].EmbedUpscaled)
+		assert.Equal(t, 51, faces[0].EmbedDetail)
 	})
 	t.Run("MeasuredAgainstTheFallbackCrop", func(t *testing.T) {
 		// The unaligned branch resamples a 160 px box rather than the 112 px template, so the
@@ -134,7 +134,7 @@ func TestGenerateEmbeddings(t *testing.T) {
 		require.Equal(t, 1, GenerateEmbeddings(embedder, fileName, faces, false))
 
 		assert.Equal(t, 57, faces[0].ThumbSize)
-		assert.Equal(t, 36, faces[0].EmbedUpscaled)
+		assert.Equal(t, 36, faces[0].EmbedDetail)
 	})
 	t.Run("EmptyEmbeddingIsNotCounted", func(t *testing.T) {
 		// The count describes vectors, so a crop the model returned nothing for is not one.
@@ -144,7 +144,7 @@ func TestGenerateEmbeddings(t *testing.T) {
 
 		require.Len(t, embedder.sizes, 1, "the crop was still taken")
 		assert.True(t, faces[0].Embeddings.Empty())
-		assert.Zero(t, faces[0].EmbedUpscaled, "a crop no vector came out of describes nothing")
+		assert.Zero(t, faces[0].EmbedDetail, "a crop no vector came out of describes nothing")
 	})
 	t.Run("UnalignedModelUsesThumbCrop", func(t *testing.T) {
 		embedder := &stubEmbedder{aligned: false, dims: 512}

internal/entity/file.go

@@ -897,7 +897,7 @@ func (m *File) AddFace(f face.Face, subjUid string) {
 			// From the marker this detection would have created, so an upgrade records the
 			// sampling exactly as a new marker does. Unmeasured stays at the sentinel rather
 			// than keeping a value recorded for another sampling.
-			thumbSize, embedUpscaled := marker.ThumbSize, marker.EmbedUpscaled
+			thumbSize, embedDetail := marker.ThumbSize, marker.EmbedDetail
 
 			// For an already-saved marker, persist first and mutate in-memory
 			// only on success: a failed write must not leave an unpersisted
@@ -913,7 +913,7 @@ func (m *File) AddFace(f face.Face, subjUid string) {
 					"detect_model":    f.DetectModel,
 					"landmarks_json":  landmarks,
 					"thumb_size":      thumbSize,
-					"embed_upscaled":  embedUpscaled,
+					"embed_detail":    embedDetail,
 					"score":           f.Score,
 				}
 
@@ -926,7 +926,7 @@ func (m *File) AddFace(f face.Face, subjUid string) {
 			existing.SetEmbeddings(f.Embeddings, f.EmbedModel, f.DetectModel)
 			existing.LandmarksJSON = landmarks
 			existing.ThumbSize = thumbSize
-			existing.EmbedUpscaled = embedUpscaled
+			existing.EmbedDetail = embedDetail
 			existing.Score = f.Score
 		}
 

internal/entity/file_test.go

@@ -712,14 +712,14 @@ func TestFile_AddFaceUpgradesProvenance(t *testing.T) {
 	file.markers = &markers
 
 	f := face.Face{
-		Rows:          2000,
-		Cols:          3000,
-		Score:         88,
-		Area:          face.NewArea("face", 1000, 1500, 300),
-		Embeddings:    face.Embeddings{face.RandomEmbedding()},
-		EmbedModel:    face.EmbeddingModelName(),
-		ThumbSize:     97,
-		EmbedUpscaled: 87,
+		Rows:        2000,
+		Cols:        3000,
+		Score:       88,
+		Area:        face.NewArea("face", 1000, 1500, 300),
+		Embeddings:  face.Embeddings{face.RandomEmbedding()},
+		EmbedModel:  face.EmbeddingModelName(),
+		ThumbSize:   97,
+		EmbedDetail: 87,
 	}
 
 	file.AddFace(f, "")
@@ -728,10 +728,10 @@ func TestFile_AddFaceUpgradesProvenance(t *testing.T) {
 	require.NoError(t, UnscopedDb().First(stored, "marker_uid = ?", existing.MarkerUID).Error)
 
 	assert.Equal(t, 97, stored.ThumbSize, "the extent the vector was sampled at must be recorded")
-	assert.Equal(t, 87, stored.EmbedUpscaled, "and how much of the crop that extent supplied")
+	assert.Equal(t, 87, stored.EmbedDetail, "and how much of the crop that extent supplied")
 	assert.Equal(t, 88, stored.Score, "the score must come from the detector that produced the vector")
 	assert.Equal(t, 97, (*file.Markers())[0].ThumbSize, "and the in-memory marker must match the row")
-	assert.Equal(t, 87, (*file.Markers())[0].EmbedUpscaled)
+	assert.Equal(t, 87, (*file.Markers())[0].EmbedDetail)
 }
 
 func TestFile_ValidFaceCount(t *testing.T) {

internal/entity/marker.go

@@ -52,17 +52,17 @@ type Marker struct {
 	H              float32         `gorm:"type:FLOAT;" json:"H" yaml:"H,omitempty"`
 	Size           int             `gorm:"default:-1;" json:"Size" yaml:"Size,omitempty"`
 	ThumbSize      int             `gorm:"column:thumb_size;default:-1;" json:"ThumbSize" yaml:"ThumbSize,omitempty"`
-	// EmbedUpscaled is the percentage of the crop its source supplied, 100 where it supplied all
-	// of it, EmbedUpscaledUnknown where a migration sampled the marker without measuring one, and
+	// EmbedDetail is the percentage of the crop its source supplied, 100 where it supplied all
+	// of it, EmbedDetailUnknown where a migration sampled the marker without measuring one, and
 	// -1 where nothing has. It describes the embedding, which is why it sits beside embed_model
 	// rather than under the thumb_ prefix its partner thumb_size carries, and it is written under
 	// the same condition as that partner so the two cannot disagree about what was sampled.
-	EmbedUpscaled int        `gorm:"column:embed_upscaled;type:SMALLINT;default:-1;" json:"-" yaml:"EmbedUpscaled,omitempty"`
-	Score         int        `gorm:"type:SMALLINT;" json:"Score" yaml:"Score,omitempty"`
-	Thumb         string     `gorm:"type:VARBINARY(128);index;default:'';" json:"Thumb" yaml:"Thumb,omitempty"`
-	MatchedAt     *time.Time `sql:"index" json:"MatchedAt" yaml:"MatchedAt,omitempty"`
-	CreatedAt     time.Time
-	UpdatedAt     time.Time
+	EmbedDetail int        `gorm:"column:embed_detail;type:SMALLINT;default:-1;" json:"-" yaml:"EmbedDetail,omitempty"`
+	Score       int        `gorm:"type:SMALLINT;" json:"Score" yaml:"Score,omitempty"`
+	Thumb       string     `gorm:"type:VARBINARY(128);index;default:'';" json:"Thumb" yaml:"Thumb,omitempty"`
+	MatchedAt   *time.Time `sql:"index" json:"MatchedAt" yaml:"MatchedAt,omitempty"`
+	CreatedAt   time.Time
+	UpdatedAt   time.Time
 }
 
 // TableName returns the entity table name.
@@ -100,7 +100,7 @@ func NewMarker(file File, area crop.Area, subjUID, markerSrc, markerType string,
 		H:             area.H,
 		Size:          size,
 		ThumbSize:     -1,
-		EmbedUpscaled: -1,
+		EmbedDetail:   -1,
 		Score:         score,
 		Thumb:         area.Thumb(file.FileHash),
 		MatchedAt:     nil,
@@ -141,8 +141,8 @@ func NewFaceMarker(f face.Face, file File, subjUid string) *Marker {
 	if f.ThumbSize > 0 {
 		m.ThumbSize = f.ThumbSize
 
-		if f.EmbedUpscaled > 0 {
-			m.EmbedUpscaled = f.EmbedUpscaled
+		if f.EmbedDetail > 0 {
+			m.EmbedDetail = f.EmbedDetail
 		}
 	}
 

internal/entity/marker_size.go

@@ -33,11 +33,11 @@ func ClusterSizeCond(alias string, floor int) (string, []any) {
 // 1, and telling them apart is what lets a migration filling the column terminate.
 const ThumbSizeUnmeasured = -2
 
-// EmbedUpscaledUnknown marks a marker a migration sampled without the share of the crop its
+// EmbedDetailUnknown marks a marker a migration sampled without the share of the crop its
 // source supplied being measurable, beside the ThumbSizeUnmeasured its partner column records for
 // the same pass. Negative rather than zero for the same reason as that one: GORM omits a zero
 // field on insert where the column has a default, so a zero would read back as never sampled.
-const EmbedUpscaledUnknown = -2
+const EmbedDetailUnknown = -2
 
 // ThumbSizeSettled reports whether a sampling has answered for this marker's extent, either by
 // measuring one or by trying and failing. Only an unsettled marker is worth sampling again.

internal/entity/marker_size_test.go

@@ -146,23 +146,23 @@ func TestMarkerThumbSize(t *testing.T) {
 	})
 }
 
-// TestNewFaceMarkerEmbedUpscaled pins the states a stored marker distinguishes, since a column
+// TestNewFaceMarkerEmbedDetail pins the states a stored marker distinguishes, since a column
 // that only ever holds two of them is a bool that cost a SMALLINT.
-func TestNewFaceMarkerEmbedUpscaled(t *testing.T) {
+func TestNewFaceMarkerEmbedDetail(t *testing.T) {
 	file := FileFixtures.Get("exampleFileName.jpg")
 	area := face.NewArea("face", 300, 300, 200)
 
 	t.Run("FullDetail", func(t *testing.T) {
-		f := face.Face{Rows: 720, Cols: 720, Area: area, ThumbSize: 284, EmbedUpscaled: 100,
+		f := face.Face{Rows: 720, Cols: 720, Area: area, ThumbSize: 284, EmbedDetail: 100,
 			Embeddings: face.Embeddings{face.RandomEmbedding()}}
 
-		require.Equal(t, 100, NewFaceMarker(f, file, "").EmbedUpscaled)
+		require.Equal(t, 100, NewFaceMarker(f, file, "").EmbedDetail)
 	})
 	t.Run("Upscaled", func(t *testing.T) {
-		f := face.Face{Rows: 720, Cols: 720, Area: area, ThumbSize: 57, EmbedUpscaled: 51,
+		f := face.Face{Rows: 720, Cols: 720, Area: area, ThumbSize: 57, EmbedDetail: 51,
 			Embeddings: face.Embeddings{face.RandomEmbedding()}}
 
-		require.Equal(t, 51, NewFaceMarker(f, file, "").EmbedUpscaled)
+		require.Equal(t, 51, NewFaceMarker(f, file, "").EmbedDetail)
 	})
 	t.Run("SampledWithoutAnExtent", func(t *testing.T) {
 		// An endpoint embeds from a reused crop, which reports no source width, so neither
@@ -171,47 +171,47 @@ func TestNewFaceMarkerEmbedUpscaled(t *testing.T) {
 		f := face.Face{Rows: 720, Cols: 720, Area: area, Embeddings: face.Embeddings{face.RandomEmbedding()}}
 		m := NewFaceMarker(f, file, "")
 
-		require.Equal(t, -1, m.EmbedUpscaled)
+		require.Equal(t, -1, m.EmbedDetail)
 		assert.Equal(t, -1, m.ThumbSize)
 	})
 	t.Run("NeverSampled", func(t *testing.T) {
 		// The state every marker written before the column existed is in, and the one a hand-drawn
 		// marker stays in: nothing has taken a crop for it, so there is nothing to describe.
 		f := face.Face{Rows: 720, Cols: 720, Area: area}
 
-		require.Equal(t, -1, NewFaceMarker(f, file, "").EmbedUpscaled)
-		assert.Equal(t, -1, NewMarker(file, crop.NewArea("face", 0.4, 0.4, 0.1, 0.1), "", SrcImage, MarkerFace, 100, 50).EmbedUpscaled)
+		require.Equal(t, -1, NewFaceMarker(f, file, "").EmbedDetail)
+		assert.Equal(t, -1, NewMarker(file, crop.NewArea("face", 0.4, 0.4, 0.1, 0.1), "", SrcImage, MarkerFace, 100, 50).EmbedDetail)
 	})
 }
 
-// TestMarkerEmbedUpscaledRoundTrip pins that every state survives an insert. The unmeasurable one
+// TestMarkerEmbedDetailRoundTrip pins that every state survives an insert. The unmeasurable one
 // is negative for exactly this reason: GORM omits a zero field where the column has a default, so
 // a zero would be stored as the -1 that means the marker was never sampled.
-func TestMarkerEmbedUpscaledRoundTrip(t *testing.T) {
+func TestMarkerEmbedDetailRoundTrip(t *testing.T) {
 	file := FileFixtures.Get("exampleFileName.jpg")
 
 	stored := func(t *testing.T, value int) int {
 		t.Helper()
 
 		m := NewMarker(file, crop.NewArea("face", 0.4, 0.4, 0.1, 0.1), "", SrcImage, MarkerFace, 100, 50)
 		m.MarkerUID = rnd.GenerateUID('m')
-		m.EmbedUpscaled = value
+		m.EmbedDetail = value
 
 		require.NoError(t, Db().Create(m).Error)
 		t.Cleanup(func() { UnscopedDb().Delete(m) })
 
 		found := FindMarker(m.MarkerUID)
 		require.NotNil(t, found)
 
-		return found.EmbedUpscaled
+		return found.EmbedDetail
 	}
 
 	t.Run("Measured", func(t *testing.T) {
 		assert.Equal(t, 51, stored(t, 51))
 		assert.Equal(t, 100, stored(t, 100))
 	})
 	t.Run("Unmeasured", func(t *testing.T) {
-		assert.Equal(t, EmbedUpscaledUnknown, stored(t, EmbedUpscaledUnknown))
+		assert.Equal(t, EmbedDetailUnknown, stored(t, EmbedDetailUnknown))
 	})
 	t.Run("NeverSampled", func(t *testing.T) {
 		assert.Equal(t, -1, stored(t, -1))