From 402339e2481bd35e96576941eee3703a9b1c4b44 Mon Sep 17 00:00:00 2001
From: YR Chen <stevapple@icloud.com>
Date: Thu, 17 Jul 2025 01:24:18 +0800
Subject: [PATCH] Add a `com.apple.containerization.index.indirect` annotation
 to distinguish synthesized index (#198)

In general I believe it's clever to synthesize an index for
single-platform image manifest, but we still need a way to distinguish
it. Add a dedicated annotation is the slightest change I've come up
with, and it's also OCI compliant. With this change come in, we can work
around https://github.com/apple/container/issues/212 and imitate the
behavior of other runtime with `container`.

Note that since `cctl` is meant to be a dedicated tool for inspecting
the Containerization framework itself, I didn't apply the indirection
for it, and it will be as-is with the genuine storage.
---
 .../Image/ImageStore/ImageStore+Import.swift               | 7 ++++++-
 Sources/ContainerizationOCI/AnnotationKeys.swift           | 1 +
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/Sources/Containerization/Image/ImageStore/ImageStore+Import.swift b/Sources/Containerization/Image/ImageStore/ImageStore+Import.swift
index 730e5779..7dc4eb4a 100644
--- a/Sources/Containerization/Image/ImageStore/ImageStore+Import.swift
+++ b/Sources/Containerization/Image/ImageStore/ImageStore+Import.swift
@@ -211,7 +211,12 @@ extension ImageStore {
                 let platform = supportedPlatforms.first!
                 var root = root
                 root.platform = platform
-                let index = ContainerizationOCI.Index(schemaVersion: 2, manifests: [root])
+                let index = ContainerizationOCI.Index(
+                    schemaVersion: 2, manifests: [root],
+                    annotations: [
+                        // indicate that this is a synthesized index which is not directly user facing
+                        AnnotationKeys.containerizationIndexIndirect: "true"
+                    ])
                 return index
             default:
                 throw ContainerizationError(.internalError, message: "Failed to create index for descriptor \(root.digest), media type \(root.mediaType)")
diff --git a/Sources/ContainerizationOCI/AnnotationKeys.swift b/Sources/ContainerizationOCI/AnnotationKeys.swift
index d20b6fc7..de8d9df2 100644
--- a/Sources/ContainerizationOCI/AnnotationKeys.swift
+++ b/Sources/ContainerizationOCI/AnnotationKeys.swift
@@ -17,6 +17,7 @@
 /// AnnotationKeys contains a subset of "dictionary keys" for commonly used annotations in an OCI Image Descriptor
 /// https://github.com/opencontainers/image-spec/blob/main/annotations.md
 public struct AnnotationKeys: Codable, Sendable {
+    public static let containerizationIndexIndirect = "com.apple.containerization.index.indirect"
     public static let containerizationImageName = "com.apple.containerization.image.name"
     public static let containerdImageName = "io.containerd.image.name"
     public static let openContainersImageName = "org.opencontainers.image.ref.name"