fix(gc): use accurate audit reason for unknown-media-type prune

removeUnknownMediaTypeManifestEntries reused syncStaleManifestRemoval,
which emitted reason="staleManifestPrune" / "pruned stale manifest
entry from index" for entries pruned because their media type is
unsupported - misleading for log/audit consumers keying off reason.

Parametrize the helper (now syncManifestRemoval) so the unknown-media-type
prune emits reason="unknownMediaTypePrune" with a matching message,
while the stale-prune callsites keep their existing output. Add
audit-capture tests asserting both reasons.

Addresses a PR #4236 review comment on gc.go:245.

Signed-off-by: Sebastian Thees <thees@users.noreply.github.com>

Author: thees

pkg/storage/gc/gc.go

@@ -239,7 +239,8 @@ func (gc GarbageCollect) removeUnknownMediaTypeManifestEntries(repo string, inde
 			continue
 		}
 
-		if err := gc.syncStaleManifestRemoval(repo, desc); err != nil {
+		if err := gc.syncManifestRemoval(repo, desc, "unknownMediaTypePrune",
+			"pruned unknown media type manifest entry from index"); err != nil {
 			return err
 		}
 	}
@@ -283,7 +284,8 @@ func (gc GarbageCollect) removeStaleManifestEntries(repo string, index *ispec.In
 
 	for _, desc := range index.Manifests {
 		if !existingBlobs[desc.Digest.String()] {
-			if err := gc.syncStaleManifestRemoval(repo, desc); err != nil {
+			if err := gc.syncManifestRemoval(repo, desc, "staleManifestPrune",
+				"pruned stale manifest entry from index"); err != nil {
 				return err
 			}
 
@@ -297,7 +299,8 @@ func (gc GarbageCollect) removeStaleManifestEntries(repo string, index *ispec.In
 			}
 
 			if stale {
-				if err := gc.syncStaleManifestRemoval(repo, desc); err != nil {
+				if err := gc.syncManifestRemoval(repo, desc, "staleManifestPrune",
+					"pruned stale manifest entry from index"); err != nil {
 					return err
 				}
 
@@ -319,11 +322,12 @@ func (gc GarbageCollect) removeStaleManifestEntries(repo string, index *ispec.In
 	return nil
 }
 
-// syncStaleManifestRemoval best-effort syncs metaDB before a stale descriptor is removed from
-// index.Manifests (index.json is persisted later in cleanRepo). metaDB failures are logged but
-// do not abort stale pruning — storage repair must not depend on secondary index consistency.
-// The blob is typically already absent from storage; cosign signatures are cleaned up via tag annotation.
-func (gc GarbageCollect) syncStaleManifestRemoval(repo string, desc ispec.Descriptor) error {
+// syncManifestRemoval best-effort syncs metaDB before a descriptor is removed from index.Manifests
+// (index.json is persisted later in cleanRepo). metaDB failures are logged but do not abort pruning —
+// storage repair must not depend on secondary index consistency. The blob is typically already absent
+// from storage; cosign signatures are cleaned up via tag annotation. reason/message identify which
+// prune path (stale vs. unknown media type) triggered the removal, for log/audit consumers.
+func (gc GarbageCollect) syncManifestRemoval(repo string, desc ispec.Descriptor, reason, message string) error {
 	tag, hasTag := getDescriptorTag(desc)
 	ref := tag
 	if ref == "" {
@@ -367,27 +371,27 @@ func (gc GarbageCollect) syncStaleManifestRemoval(repo string, desc ispec.Descri
 		Str("reference", ref).
 		Str("digest", desc.Digest.String()).
 		Str("decision", "delete").
-		Str("reason", "staleManifestPrune")
+		Str("reason", reason)
 
 	if subjectDigest != "" {
 		logEvent = logEvent.Str("subject", subjectDigest.String())
 	}
 
-	logEvent.Msg("pruned stale manifest entry from index")
+	logEvent.Msg(message)
 
 	if gc.auditLog != nil {
 		auditEvent := gc.auditLog.Info().Str("module", "gc").
 			Str("repository", repo).
 			Str("reference", ref).
 			Str("digest", desc.Digest.String()).
 			Str("decision", "delete").
-			Str("reason", "staleManifestPrune")
+			Str("reason", reason)
 
 		if subjectDigest != "" {
 			auditEvent = auditEvent.Str("subject", subjectDigest.String())
 		}
 
-		auditEvent.Msg("pruned stale manifest entry from index")
+		auditEvent.Msg(message)
 	}
 
 	return nil

pkg/storage/gc/gc_test.go

@@ -3047,6 +3047,198 @@ func TestGCUnknownMediaTypeManifestPruned(t *testing.T) {
 	})
 }
 
+// auditLine is the subset of audit-log JSON fields relevant to prune-reason assertions.
+type auditLine struct {
+	Digest  string `json:"digest"`
+	Reason  string `json:"reason"`
+	Message string `json:"message"`
+}
+
+// readAuditLines parses a temp audit-log file's newline-delimited JSON entries.
+func readAuditLines(t *testing.T, path string) []auditLine {
+	t.Helper()
+
+	buf, err := os.ReadFile(path)
+	So(err, ShouldBeNil)
+
+	var lines []auditLine
+
+	for _, raw := range bytes.Split(bytes.TrimSpace(buf), []byte("\n")) {
+		if len(raw) == 0 {
+			continue
+		}
+
+		var line auditLine
+
+		err := json.Unmarshal(raw, &line)
+		So(err, ShouldBeNil)
+
+		lines = append(lines, line)
+	}
+
+	return lines
+}
+
+// TestGCUnknownMediaTypePruneReason guards that the unknown-media-type index prune emits its own
+// accurate audit reason/message, distinct from the shared stale-prune helper's output, so audit
+// consumers can tell the two prune paths apart (SPEC.md §2).
+func TestGCUnknownMediaTypePruneReason(t *testing.T) {
+	Convey("index.json entry with unsupported manifest media type", t, func() {
+		log := zlog.NewTestLogger()
+
+		auditPath := path.Join(t.TempDir(), "audit.log")
+		audit := zlog.NewAuditLogger("debug", auditPath)
+
+		metrics := newTestMetricsServer(t, log)
+
+		rootDir := t.TempDir()
+		imgStore := local.NewImageStore(rootDir, false, false, log, metrics, nil, nil, nil, nil)
+
+		storeController := storage.StoreController{}
+		storeController.DefaultStore = imgStore
+
+		ctx := context.Background()
+		repoName := "gc-unknown-media-type-reason"
+
+		unsupportedMediaType := "application/vnd.oci.artifact.manifest.v1+json"
+
+		unknown := CreateRandomImage()
+		err := WriteImageToFileSystem(unknown, repoName, "unknown", storeController)
+		So(err, ShouldBeNil)
+
+		// rewrite the unknown image's manifest with an unsupported media type, re-hash it, write the
+		// new blob, and re-point/re-type its index.json descriptor - mirroring
+		// TestGCUnknownMediaTypeManifestPruned's fixture construction.
+		unknownBuf, err := os.ReadFile(path.Join(rootDir, repoName, "blobs",
+			unknown.ManifestDescriptor.Digest.Algorithm().String(), unknown.ManifestDescriptor.Digest.Encoded()))
+		So(err, ShouldBeNil)
+
+		var unknownManifest ispec.Manifest
+
+		err = json.Unmarshal(unknownBuf, &unknownManifest)
+		So(err, ShouldBeNil)
+
+		unknownManifest.MediaType = unsupportedMediaType
+
+		unknownBuf, err = json.Marshal(unknownManifest)
+		So(err, ShouldBeNil)
+
+		unknownDigest := godigest.FromBytes(unknownBuf)
+
+		err = os.WriteFile(path.Join(rootDir, repoName, "blobs", unknownDigest.Algorithm().String(), unknownDigest.Encoded()),
+			unknownBuf, storageConstants.DefaultFilePerms)
+		So(err, ShouldBeNil)
+
+		indexJSONBuf, err := os.ReadFile(path.Join(rootDir, repoName, "index.json"))
+		So(err, ShouldBeNil)
+
+		var indexJSON ispec.Index
+
+		err = json.Unmarshal(indexJSONBuf, &indexJSON)
+		So(err, ShouldBeNil)
+
+		for idx, desc := range indexJSON.Manifests {
+			if desc.Digest == unknown.ManifestDescriptor.Digest {
+				indexJSON.Manifests[idx].Digest = unknownDigest
+				indexJSON.Manifests[idx].MediaType = unsupportedMediaType
+			}
+		}
+
+		indexJSONBuf, err = json.Marshal(indexJSON)
+		So(err, ShouldBeNil)
+
+		err = os.WriteFile(path.Join(rootDir, repoName, "index.json"), indexJSONBuf, storageConstants.DefaultFilePerms)
+		So(err, ShouldBeNil)
+
+		time.Sleep(1 * time.Second)
+
+		gcInstance := gc.NewGarbageCollect(imgStore, nil, gc.Options{
+			Delay: 1 * time.Second,
+			ImageRetention: config.ImageRetention{
+				Delay: 1 * time.Second,
+			},
+		}, audit, log, metrics)
+
+		err = gcInstance.CleanRepo(ctx, repoName)
+		So(err, ShouldBeNil)
+
+		lines := readAuditLines(t, auditPath)
+
+		var found *auditLine
+
+		for idx := range lines {
+			if lines[idx].Digest == unknownDigest.String() {
+				found = &lines[idx]
+
+				break
+			}
+		}
+
+		So(found, ShouldNotBeNil)
+		So(found.Reason, ShouldEqual, "unknownMediaTypePrune")
+		So(found.Message, ShouldEqual, "pruned unknown media type manifest entry from index")
+	})
+}
+
+// TestGCStaleManifestPruneReason is the AC-2 regression guard: a stale-blob prune (missing blob path,
+// removeStaleManifestEntries) must keep emitting the unchanged "staleManifestPrune" reason/message after
+// syncManifestRemoval was parametrized for the unknown-media-type prune reason.
+func TestGCStaleManifestPruneReason(t *testing.T) {
+	Convey("index.json entry pointing at a missing blob", t, func() {
+		log := zlog.NewTestLogger()
+
+		auditPath := path.Join(t.TempDir(), "audit.log")
+		audit := zlog.NewAuditLogger("debug", auditPath)
+
+		metrics := newTestMetricsServer(t, log)
+
+		rootDir := t.TempDir()
+		imgStore := local.NewImageStore(rootDir, false, false, log, metrics, nil, nil, nil, nil)
+
+		storeController := storage.StoreController{}
+		storeController.DefaultStore = imgStore
+
+		ctx := context.Background()
+		repoName := "gc-stale-manifest-reason"
+
+		stale := CreateRandomImage()
+		err := WriteImageToFileSystem(stale, repoName, "stale", storeController)
+		So(err, ShouldBeNil)
+
+		// delete the manifest blob itself so the descriptor points at a missing blob and is pruned by
+		// removeStaleManifestEntries's missing-blob path (gc.go's "!existingBlobs[...]" branch).
+		err = os.Remove(path.Join(rootDir, repoName, "blobs",
+			stale.ManifestDescriptor.Digest.Algorithm().String(), stale.ManifestDescriptor.Digest.Encoded()))
+		So(err, ShouldBeNil)
+
+		gcInstance := gc.NewGarbageCollect(imgStore, nil, gc.Options{
+			Delay: 1 * time.Second,
+			ImageRetention: config.ImageRetention{
+				Delay: 1 * time.Second,
+			},
+		}, audit, log, metrics)
+
+		err = gcInstance.CleanRepo(ctx, repoName)
+		So(err, ShouldBeNil)
+
+		lines := readAuditLines(t, auditPath)
+
+		var found *auditLine
+
+		for idx := range lines {
+			if lines[idx].Digest == stale.ManifestDescriptor.Digest.String() {
+				found = &lines[idx]
+
+				break
+			}
+		}
+
+		So(found, ShouldNotBeNil)
+		So(found.Reason, ShouldEqual, "staleManifestPrune")
+		So(found.Message, ShouldEqual, "pruned stale manifest entry from index")
+	})
+}
+
 // TestGCDryRunDeletesNothing guards DryRun's non-destructive-simulation contract: index.json pruning is
 // already DryRun-gated, but blob GC re-reads the on-disk index.json independently and used to run
 // unconditionally, so it could delete orphan blobs for real - including the config/layers of an