@caelo-cms/provisioning 0.10.65 → 0.10.66

package/src/upgrade/__tests__/live-indexes.ts

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The v0.10.64 admin + gateway image indexes exactly as the release mirror
+ * serves them (fixtures/, byte for byte), and a fake `fetch` that serves
+ * them by digest — the shapes of #1025: each index lists its linux/amd64
+ * manifest plus one buildx attestation manifest, and Cloud Run records the
+ * linux/amd64 digest for a serving revision.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const fixture = (name: string): Uint8Array<ArrayBuffer> =>
+  new Uint8Array(readFileSync(join(import.meta.dir, "fixtures", name)));
+
+/** v0.10.64 admin: the index the signed manifest names, and what it lists. */
+export const ADMIN_INDEX =
+  "sha256:bcda1725a5390c910c56cfedb6f55bc4f38cebb0231e9e9b4297bb5c08aec3e0";
+export const ADMIN_AMD64 =
+  "sha256:2e75b714662ec6b17d32666b546378e2850920950076c4e911deddc05596e656";
+export const ADMIN_ATTESTATION =
+  "sha256:06f9defdb92e8252e9faab8fcb8fb340d3949d5cdec09e06b42905ade7ba30c0";
+/** v0.10.64 gateway. */
+export const GATEWAY_INDEX =
+  "sha256:fbb0be7a106f75c25e44bca1898fd56af27d11fa599659afe55e4f6ffaeca4a3";
+export const GATEWAY_AMD64 =
+  "sha256:d24f2675d43e7891f217938c74475e9c31a64ffda0c96cf4fbb0a3f73e31367e";
+
+/** The index bytes, by digest. */
+export const LIVE_INDEXES: Readonly<Record<string, Uint8Array<ArrayBuffer>>> = {
+  [ADMIN_INDEX]: fixture("admin-0.10.64-index.json"),
+  [GATEWAY_INDEX]: fixture("gateway-0.10.64-index.json"),
+};
+
+/** How the fake registry answers. */
+export interface FakeRegistryOptions {
+  /** Answer every request with this HTTP status instead. */
+  readonly status?: number;
+  /** Throw (network failure) instead of answering. */
+  readonly unreachable?: boolean;
+  /** Serve these bytes for every digest (a tampering registry). */
+  readonly tampered?: Uint8Array<ArrayBuffer>;
+  /** Index bytes to serve besides {@link LIVE_INDEXES}. */
+  readonly extra?: Readonly<Record<string, Uint8Array<ArrayBuffer>>>;
+}
+
+/** A `fetch` serving the mirror's `/v2/<repo>/manifests/<digest>`; records each URL in `calls`. */
+export function fakeRegistryFetch(calls: string[], opts: FakeRegistryOptions = {}): typeof fetch {
+  const impl = async (input: string | URL | Request): Promise<Response> => {
+    const url = String(input instanceof Request ? input.url : input);
+    calls.push(url);
+    if (opts.unreachable) throw new Error("getaddrinfo ENOTFOUND");
+    if (opts.status) return new Response("", { status: opts.status });
+    const digest = url.split("/manifests/")[1] ?? "";
+    const bytes = opts.tampered ?? opts.extra?.[digest] ?? LIVE_INDEXES[digest];
+    if (!bytes) return new Response("", { status: 404 });
+    return new Response(bytes, { status: 200 });
+  };
+  return impl as typeof fetch;
+}

package/src/upgrade/gcp-lookup.test.ts

@@ -1,10 +1,11 @@
 // SPDX-License-Identifier: MPL-2.0
 
 /**
- * findServingImage against a fake gcloud: the digest a revision was deployed
- * with is the release's index digest, Cloud Run's `status.imageDigest` the
- * platform manifest inside it (#860). Both must come back, so a recorded
- * index digest matches what serves.
+ * findServingImage against a fake gcloud. A revision's spec and
+ * `status.imageDigest` may name the release's index digest or the
+ * platform manifest inside it (#860); on live installs BOTH name the
+ * platform manifest (#1025), and only the service template keeps the index
+ * (findTemplateImageDigest). Every digest found must come back.
  */
 
 import { describe, expect, it } from "bun:test";
@@ -12,6 +13,7 @@ import type { GcloudResult } from "../gcloud.js";
 import type { GcloudRunner } from "../gcloud-retry.js";
 import {
   findServingImage,
+  findTemplateImageDigest,
   lookupFailure,
   resolveGcpResourceName,
   servingImageDigests,
@@ -108,15 +110,15 @@ const revision = (image: string, imageDigest?: string) =>
   ok(JSON.stringify({ spec: { containers: [{ image }] }, status: { imageDigest } }));
 
 describe("findServingImage", () => {
-  it("returns the deployed index digest and the platform digest Cloud Run resolved", async () => {
+  it("returns the spec's index digest and the platform digest Cloud Run resolved", async () => {
     const image = await findServingImage(
       gcloud(revision(`${REPO}@${INDEX}`, `${REPO}@${PLATFORM}`)),
       "acme",
       "europe-west1",
       "caelo-production-admin-x",
     );
-    expect(image).toEqual({ deployedDigest: INDEX, resolvedDigest: PLATFORM });
-    expect(servingImageDigests(image ?? { deployedDigest: null, resolvedDigest: null })).toEqual([
+    expect(image).toEqual({ specDigest: INDEX, resolvedDigest: PLATFORM });
+    expect(servingImageDigests(image ?? { specDigest: null, resolvedDigest: null })).toEqual([
       INDEX,
       PLATFORM,
     ]);
@@ -129,11 +131,26 @@ describe("findServingImage", () => {
       "europe-west1",
       "svc",
     );
-    expect(image).toEqual({ deployedDigest: null, resolvedDigest: PLATFORM });
+    expect(image).toEqual({ specDigest: null, resolvedDigest: PLATFORM });
+  });
+
+  it("regression #1025: the live shape, spec and status both name the platform manifest", async () => {
+    // caelo-production-admin-482044c-00015-2vc on searchviu-website, deployed
+    // as the v0.10.64 index admin@sha256:bcda… (the service template).
+    const live = `${REPO}@sha256:2e75b714662ec6b17d32666b546378e2850920950076c4e911deddc05596e656`;
+    const image = await findServingImage(
+      gcloud(revision(live, live)),
+      "acme",
+      "europe-west1",
+      "svc",
+    );
+    expect(servingImageDigests(image ?? { specDigest: null, resolvedDigest: null })).toEqual([
+      "sha256:2e75b714662ec6b17d32666b546378e2850920950076c4e911deddc05596e656",
+    ]);
   });
 
   it("one digest when both name the same image", () => {
-    expect(servingImageDigests({ deployedDigest: INDEX, resolvedDigest: INDEX })).toEqual([INDEX]);
+    expect(servingImageDigests({ specDigest: INDEX, resolvedDigest: INDEX })).toEqual([INDEX]);
   });
 
   it("null when no digest can be read or the output is not JSON", async () => {
@@ -157,3 +174,30 @@ describe("findServingImage", () => {
     ).toBeNull();
   });
 });
+
+describe("findTemplateImageDigest (#1025)", () => {
+  const service = (image: unknown) =>
+    ok(JSON.stringify({ spec: { template: { spec: { containers: [{ image }] } } } }));
+  const runner =
+    (r: GcloudResult): GcloudRunner =>
+    async () =>
+      r;
+
+  it("reads the index digest the template pins", async () => {
+    expect(
+      await findTemplateImageDigest(runner(service(`${REPO}@${INDEX}`)), "acme", "r", "svc"),
+    ).toBe(INDEX);
+  });
+
+  it("null for a tag, an odd shape, bad JSON or a failed describe", async () => {
+    for (const r of [
+      service(`${REPO}:latest`),
+      service(7),
+      ok("null"),
+      ok("not json"),
+      fail("denied"),
+    ]) {
+      expect(await findTemplateImageDigest(runner(r), "acme", "r", "svc")).toBeNull();
+    }
+  });
+});

package/src/upgrade/gcp-lookup.ts

@@ -157,28 +157,30 @@ export async function findCurrentRevision(
  * by (not the service template's: after a rollback the template names the
  * failed image while traffic stays on the previous revision).
  *
- * Why two digests (#860): Caelo's release images are OCI image *indexes*
- * (buildx adds a provenance/SBOM attestation manifest even to a
- * single-platform build), and the signed release manifest, install.json
- * and every deploy pin the index digest. Cloud Run's `status.imageDigest`
- * names what it resolved and pulled, the linux/amd64 *platform manifest*
- * inside that index, so comparing it with a recorded index digest never
- * matches. The digest the revision was deployed with
- * (`spec.containers[0].image`, `…@sha256:<index>`) is the form everything
- * else records; it is content-addressed, so the revision necessarily runs
- * that index's image.
+ * Which form these digests take (#860, corrected by #1025): Caelo's release
+ * images are OCI image *indexes* (buildx adds a provenance/SBOM attestation
+ * manifest even to a single-platform build), and the signed release
+ * manifest, install.json and every deploy pin the index digest. Cloud Run
+ * resolves that index to its linux/amd64 *platform manifest* and records
+ * the platform digest — in `status.imageDigest` AND, contrary to what #860
+ * assumed, in the revision's `spec.containers[0].image` too: a revision
+ * deployed as `admin@sha256:bcda…` (the v0.10.64 index) reads back as
+ * `admin@sha256:2e75…` in both fields (live installs, 2026-10-23). Only the
+ * service template keeps the index. So these digests are matched against a
+ * release's index AND the platform manifests inside it
+ * (upgrade/image-forms.ts), never against the index alone.
  */
 export interface ServingImage {
-  /** The digest the revision was deployed with; null when deployed by tag. */
-  readonly deployedDigest: string | null;
+  /** The digest the revision's `spec.containers[0].image` names; null when it names a tag. */
+  readonly specDigest: string | null;
   /** The digest Cloud Run resolved and runs (`status.imageDigest`); null when not reported. */
   readonly resolvedDigest: string | null;
 }
 
-/** Every digest `image` is known by, deployed form first. */
+/** Every digest `image` is known by, spec form first. */
 export function servingImageDigests(image: ServingImage): string[] {
   const out: string[] = [];
-  for (const d of [image.deployedDigest, image.resolvedDigest]) {
+  for (const d of [image.specDigest, image.resolvedDigest]) {
     if (d && !out.includes(d)) out.push(d);
   }
   return out;
@@ -231,12 +233,55 @@ export async function findServingImage(
   const digestOf = (ref: string | undefined): string | null =>
     ref === undefined ? null : (PINNED_DIGEST.exec(ref.trim())?.[1] ?? null);
   const image: ServingImage = {
-    deployedDigest: digestOf(parsed.data.spec?.containers?.[0]?.image),
+    specDigest: digestOf(parsed.data.spec?.containers?.[0]?.image),
     resolvedDigest: digestOf(parsed.data.status?.imageDigest),
   };
   return servingImageDigests(image).length > 0 ? image : null;
 }
 
+/** The fields of `gcloud run services describe --format=json` {@link findTemplateImageDigest} reads. */
+const ServiceJsonSchema = z.object({
+  spec: z
+    .object({
+      template: z
+        .object({
+          spec: z
+            .object({
+              containers: z.array(z.object({ image: z.string().optional() })).optional(),
+            })
+            .optional(),
+        })
+        .optional(),
+    })
+    .optional(),
+});
+
+/**
+ * The digest the service's template pins (the index a deploy named, #1025),
+ * or null when it cannot be read or names a tag. NOT what serves — after a
+ * rollback the template names the failed image — so only a hint for which
+ * release to check (upgrader-records.ts).
+ */
+export async function findTemplateImageDigest(
+  run: GcloudRunner,
+  projectId: string,
+  region: string,
+  serviceName: string,
+): Promise<string | null> {
+  const stdout = await describeServiceJson(run, projectId, region, serviceName);
+  if (stdout === null) return null;
+  let json: unknown;
+  try {
+    json = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  const parsed = ServiceJsonSchema.safeParse(json);
+  if (!parsed.success) return null;
+  const ref = parsed.data.spec?.template?.spec?.containers?.[0]?.image;
+  return ref === undefined ? null : (PINNED_DIGEST.exec(ref.trim())?.[1] ?? null);
+}
+
 /** The service's own `run.app` URL. */
 export async function findServiceUrl(
   run: GcloudRunner,

package/src/upgrade/image-forms.test.ts

@@ -0,0 +1,192 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #1025: every digest a release image is known by, read from the signed
+ * manifest or from the content-checked index in the fixed mirror. Run
+ * against the v0.10.64 indexes exactly as the mirror serves them.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  ADMIN_AMD64,
+  ADMIN_ATTESTATION,
+  ADMIN_INDEX,
+  fakeRegistryFetch,
+  GATEWAY_AMD64,
+  GATEWAY_INDEX,
+  LIVE_INDEXES,
+} from "./__tests__/live-indexes.js";
+import { createReleaseImageForms, formsFromIndexJson, platformDigestsOf } from "./image-forms.js";
+
+const D = (c: string) => `sha256:${c.repeat(64)}`;
+const MIRROR = "https://europe-west1-docker.pkg.dev/v2/caelo-website/caelo-cms-images";
+
+describe("the fixtures", () => {
+  it("are the bytes of the indexes they are named after", async () => {
+    for (const [digest, bytes] of Object.entries(LIVE_INDEXES)) {
+      const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+      expect(`sha256:${Buffer.from(hash).toString("hex")}`).toBe(digest);
+    }
+  });
+});
+
+describe("createReleaseImageForms().ofIndex", () => {
+  it("regression #1025: the v0.10.64 admin index lists its linux/amd64 manifest, not the attestation", async () => {
+    const calls: string[] = [];
+    const forms = createReleaseImageForms(fakeRegistryFetch(calls));
+    const r = await forms.ofIndex("admin", ADMIN_INDEX);
+    expect(r).toEqual({ ok: true, digests: [ADMIN_INDEX, ADMIN_AMD64], amd64: ADMIN_AMD64 });
+    expect(r.ok && r.digests.includes(ADMIN_ATTESTATION)).toBe(false);
+    // Fetched by digest from the fixed mirror.
+    expect(calls).toEqual([`${MIRROR}/admin/manifests/${ADMIN_INDEX}`]);
+    expect(await forms.ofIndex("gateway", GATEWAY_INDEX)).toEqual({
+      ok: true,
+      digests: [GATEWAY_INDEX, GATEWAY_AMD64],
+      amd64: GATEWAY_AMD64,
+    });
+  });
+
+  it("reads each index once per instance", async () => {
+    const calls: string[] = [];
+    const forms = createReleaseImageForms(fakeRegistryFetch(calls));
+    await forms.ofIndex("admin", ADMIN_INDEX);
+    await forms.ofIndex("admin", ADMIN_INDEX);
+    expect(calls).toHaveLength(1);
+  });
+
+  it("refuses bytes that do not hash to the digest asked for (a tampering registry)", async () => {
+    const forged = new TextEncoder().encode(
+      JSON.stringify({
+        mediaType: "application/vnd.oci.image.index.v1+json",
+        manifests: [{ digest: D("6"), platform: { os: "linux", architecture: "amd64" } }],
+      }),
+    );
+    const forms = createReleaseImageForms(fakeRegistryFetch([], { tampered: forged }));
+    const r = await forms.ofIndex("admin", ADMIN_INDEX);
+    expect(r.ok).toBe(false);
+    expect(r.ok ? null : r.transient).toBe(false);
+    expect(r.ok ? "" : r.message).toContain("does not match its digest");
+  });
+
+  it("an outage is transient, a missing index is not", async () => {
+    for (const [opts, transient] of [
+      [{ status: 503 }, true],
+      [{ status: 429 }, true],
+      [{ unreachable: true }, true],
+      [{ status: 404 }, false],
+    ] as const) {
+      const r = await createReleaseImageForms(fakeRegistryFetch([], opts)).ofIndex(
+        "admin",
+        ADMIN_INDEX,
+      );
+      expect(r.ok ? null : r.transient).toBe(transient);
+    }
+  });
+
+  it("follows the registry's anonymous Bearer challenge", async () => {
+    const calls: string[] = [];
+    const inner = fakeRegistryFetch(calls);
+    const challenged = (async (input: string | URL | Request, init?: RequestInit) => {
+      const url = String(input);
+      if (url.startsWith("https://token.example/")) {
+        return Response.json({ token: "anon" });
+      }
+      const auth = new Headers(init?.headers).get("authorization");
+      if (auth !== "Bearer anon") {
+        return new Response("", {
+          status: 401,
+          headers: { "www-authenticate": 'Bearer realm="https://token.example/t",service="x"' },
+        });
+      }
+      return inner(input, init);
+    }) as typeof fetch;
+    const r = await createReleaseImageForms(challenged).ofIndex("admin", ADMIN_INDEX);
+    expect(r.ok && r.amd64).toBe(ADMIN_AMD64);
+  });
+});
+
+describe("createReleaseImageForms().of", () => {
+  it("takes the signed platform digests without a registry round trip", async () => {
+    const calls: string[] = [];
+    const forms = createReleaseImageForms(fakeRegistryFetch(calls));
+    const m = {
+      version: "0.10.66",
+      digests: { admin: D("a"), gateway: D("b"), ops: D("c") },
+      platformDigests: { admin: D("1"), gateway: D("2"), ops: D("3") },
+    };
+    expect(await forms.of(m, "gateway")).toEqual({
+      ok: true,
+      digests: [D("b"), D("2")],
+      amd64: D("2"),
+    });
+    expect(calls).toEqual([]);
+  });
+
+  it("reads the index for a release signed before the field", async () => {
+    const forms = createReleaseImageForms(fakeRegistryFetch([]));
+    const m = {
+      version: "0.10.64",
+      digests: { admin: ADMIN_INDEX, gateway: GATEWAY_INDEX, ops: D("c") },
+    };
+    expect(await forms.of(m, "admin")).toMatchObject({ ok: true, amd64: ADMIN_AMD64 });
+  });
+});
+
+describe("formsFromIndexJson", () => {
+  it("a plain image manifest is its own platform form", () => {
+    const plain = { mediaType: "application/vnd.oci.image.manifest.v1+json", config: {} };
+    expect(formsFromIndexJson(D("7"), plain)).toEqual({
+      ok: true,
+      digests: [D("7")],
+      amd64: D("7"),
+    });
+  });
+
+  it("an index without a linux/amd64 manifest has no amd64 form", () => {
+    const arm = {
+      mediaType: "application/vnd.oci.image.index.v1+json",
+      manifests: [{ digest: D("8"), platform: { os: "linux", architecture: "arm64" } }],
+    };
+    expect(formsFromIndexJson(D("7"), arm)).toEqual({
+      ok: true,
+      digests: [D("7"), D("8")],
+      amd64: null,
+    });
+  });
+
+  it("an unreadable shape is a non-transient error", () => {
+    const r = formsFromIndexJson(D("7"), { manifests: [{ digest: "nope" }] });
+    expect(r.ok ? null : r.transient).toBe(false);
+  });
+});
+
+describe("platformDigestsOf", () => {
+  it("reads the linux/amd64 form of both indexes", async () => {
+    const forms = createReleaseImageForms(fakeRegistryFetch([]));
+    expect(await platformDigestsOf({ admin: ADMIN_INDEX, gateway: GATEWAY_INDEX }, forms)).toEqual({
+      ok: true,
+      platformDigests: { admin: ADMIN_AMD64, gateway: GATEWAY_AMD64 },
+    });
+  });
+
+  it("prefers the manifest's signed forms when it signs these very indexes", async () => {
+    const calls: string[] = [];
+    const forms = createReleaseImageForms(fakeRegistryFetch(calls));
+    const m = {
+      version: "0.10.66",
+      digests: { admin: D("a"), gateway: D("b"), ops: D("c") },
+      platformDigests: { admin: D("1"), gateway: D("2"), ops: D("3") },
+    };
+    expect(await platformDigestsOf({ admin: D("a"), gateway: D("b") }, forms, m)).toEqual({
+      ok: true,
+      platformDigests: { admin: D("1"), gateway: D("2") },
+    });
+    expect(calls).toEqual([]);
+  });
+
+  it("says why when an index cannot be read", async () => {
+    const forms = createReleaseImageForms(fakeRegistryFetch([], { status: 503 }));
+    const r = await platformDigestsOf({ admin: ADMIN_INDEX, gateway: GATEWAY_INDEX }, forms);
+    expect(r.ok ? "" : r.message).toContain("HTTP 503");
+  });
+});

package/src/upgrade/image-forms.ts

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Every digest a release image is known by (#1025).
+ *
+ * Caelo's release images are OCI image *indexes*: buildx adds a
+ * provenance/SBOM attestation manifest even to a single-platform build. The
+ * signed release manifest, install.json and every deploy pin the index
+ * digest, but Cloud Run resolves the index to its linux/amd64 *platform
+ * manifest* and records that digest — in the revision's `status.imageDigest`
+ * AND in its `spec.containers[0].image` (verified on live installs,
+ * 2026-10-23: a revision deployed as `admin@sha256:bcda…` (the v0.10.64
+ * index) reads back as `admin@sha256:2e75…`, its linux/amd64 manifest). So
+ * "does release X serve?" must compare the serving digest with every form of
+ * X's images, not just the index.
+ *
+ * Where the forms come from, in order of trust:
+ *   1. the release manifest's signed `platformDigests` (releases cut after
+ *      #1025) — no registry round trip;
+ *   2. otherwise the index itself, fetched BY DIGEST from the fixed public
+ *      mirror and checked against that digest before it is read. Content
+ *      addressing makes it as unforgeable as the signature that named the
+ *      index: a registry or proxy that altered it fails the check.
+ *
+ * Only platform manifests count, never the attestation manifests listed next
+ * to them (Cloud Run cannot run those). Lookups are cached per instance, so
+ * one upgrader run fetches each index at most once.
+ */
+
+import { z } from "zod";
+import type { ImageDigests } from "../install-state.js";
+import type { ReleaseManifest } from "../release-manifest.js";
+import type { RollSlug } from "./app-roll.js";
+import { fetchRegistryManifest, IMAGE_DIGEST, RELEASE_REGISTRY } from "./release-images.js";
+
+/** The digests one release image is known by. */
+export type ImageFormsResult =
+  | {
+      readonly ok: true;
+      /** The index digest first, then each platform manifest it lists. */
+      readonly digests: readonly string[];
+      /**
+       * The linux/amd64 form Cloud Run runs: the signed platform digest, the
+       * index's linux/amd64 entry, or the digest itself when it names a plain
+       * image manifest. Null when the index lists no linux/amd64 manifest.
+       */
+      readonly amd64: string | null;
+    }
+  | {
+      readonly ok: false;
+      /** A retry may cure it (registry unreachable, 5xx, 429). */
+      readonly transient: boolean;
+      readonly message: string;
+    };
+
+/** Finds every form of a release image; see the file comment. */
+export interface ReleaseImageForms {
+  /** The forms of release `m`'s image `slug` (signed platform digests win). */
+  of(
+    m: Pick<ReleaseManifest, "version" | "digests" | "platformDigests">,
+    slug: RollSlug,
+  ): Promise<ImageFormsResult>;
+  /** The forms of the index `indexDigest` of image `slug`, read from the mirror. */
+  ofIndex(slug: RollSlug, indexDigest: string): Promise<ImageFormsResult>;
+}
+
+const INDEX_MEDIA_TYPES = new Set([
+  "application/vnd.oci.image.index.v1+json",
+  "application/vnd.docker.distribution.manifest.list.v2+json",
+]);
+
+const digest = z.string().regex(IMAGE_DIGEST);
+
+/** The fields of an image index (or plain image manifest) the lookup reads. */
+const ManifestJsonSchema = z.object({
+  mediaType: z.string().optional(),
+  manifests: z
+    .array(
+      z.object({
+        digest,
+        platform: z.object({ os: z.string(), architecture: z.string() }).optional(),
+        annotations: z.record(z.string(), z.string()).optional(),
+      }),
+    )
+    .optional(),
+});
+
+async function sha256Digest(bytes: Uint8Array<ArrayBuffer>): Promise<string> {
+  const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+  return `sha256:${[...hash].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
+/**
+ * Read the forms out of index bytes already checked against `indexDigest`.
+ * Exported for tests; production code goes through {@link createReleaseImageForms}.
+ */
+export function formsFromIndexJson(indexDigest: string, json: unknown): ImageFormsResult {
+  const parsed = ManifestJsonSchema.safeParse(json);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      transient: false,
+      message: `${indexDigest} is not an image index or manifest: ${parsed.error.message}`,
+    };
+  }
+  const { mediaType, manifests } = parsed.data;
+  const isIndex = mediaType ? INDEX_MEDIA_TYPES.has(mediaType) : manifests !== undefined;
+  // A plain image manifest is its own platform form.
+  if (!isIndex) return { ok: true, digests: [indexDigest], amd64: indexDigest };
+  const platforms = (manifests ?? []).filter(
+    (m) =>
+      m.annotations?.["vnd.docker.reference.type"] !== "attestation-manifest" &&
+      m.platform !== undefined &&
+      m.platform.os !== "unknown",
+  );
+  const amd64 = platforms.filter(
+    (m) => m.platform?.os === "linux" && m.platform.architecture === "amd64",
+  );
+  return {
+    ok: true,
+    digests: [indexDigest, ...platforms.map((m) => m.digest).filter((d) => d !== indexDigest)],
+    amd64: amd64.length === 1 ? (amd64[0]?.digest ?? null) : null,
+  };
+}
+
+/**
+ * The lookup against the fixed public mirror ({@link RELEASE_REGISTRY}),
+ * anonymous, cached per instance.
+ *
+ * @param fetchImpl - injectable for tests; the real one by default
+ */
+export function createReleaseImageForms(fetchImpl: typeof fetch = fetch): ReleaseImageForms {
+  const cache = new Map<string, Promise<ImageFormsResult>>();
+  const { region, project, repo } = RELEASE_REGISTRY;
+
+  async function lookup(slug: RollSlug, indexDigest: string): Promise<ImageFormsResult> {
+    const where = `the ${slug} image index ${indexDigest} in the release mirror`;
+    const fetched = await fetchRegistryManifest(
+      `${region}-docker.pkg.dev`,
+      `${project}/${repo}/${slug}`,
+      indexDigest,
+      fetchImpl,
+    );
+    if (!fetched.ok) {
+      return {
+        ok: false,
+        transient: fetched.transient,
+        message: `${where} could not be read (${fetched.reason})`,
+      };
+    }
+    const actual = await sha256Digest(fetched.bytes);
+    if (actual !== indexDigest) {
+      return {
+        ok: false,
+        transient: false,
+        message: `${where} does not match its digest (${actual} served): the registry or a proxy altered it`,
+      };
+    }
+    let json: unknown;
+    try {
+      json = JSON.parse(new TextDecoder().decode(fetched.bytes));
+    } catch {
+      return { ok: false, transient: false, message: `${where} is not JSON` };
+    }
+    return formsFromIndexJson(indexDigest, json);
+  }
+
+  const ofIndex = (slug: RollSlug, indexDigest: string): Promise<ImageFormsResult> => {
+    const key = `${slug}@${indexDigest}`;
+    let pending = cache.get(key);
+    if (!pending) {
+      pending = lookup(slug, indexDigest);
+      cache.set(key, pending);
+    }
+    return pending;
+  };
+
+  return {
+    ofIndex,
+    of: async (m, slug) => {
+      const signed = m.platformDigests?.[slug];
+      if (signed) {
+        const index = m.digests[slug];
+        return { ok: true, digests: [index, ...(signed === index ? [] : [signed])], amd64: signed };
+      }
+      return ofIndex(slug, m.digests[slug]);
+    },
+  };
+}
+
+/**
+ * The linux/amd64 form of each image in `digests`, to record next to them
+ * in install.json (#1025). Taken from `manifest`'s signed platform digests
+ * when it signs these very indexes, else from the content-checked index.
+ *
+ * @returns the forms, or why they are not known (the caller records the
+ *   index digests without them; the upgrader then reads the index itself)
+ */
+export async function platformDigestsOf(
+  digests: ImageDigests,
+  forms: ReleaseImageForms,
+  manifest?: Pick<ReleaseManifest, "version" | "digests" | "platformDigests"> | null,
+): Promise<
+  | { readonly ok: true; readonly platformDigests: ImageDigests }
+  | { readonly ok: false; readonly message: string }
+> {
+  const out: Partial<Record<RollSlug, string>> = {};
+  for (const slug of ["admin", "gateway"] as const) {
+    const found =
+      manifest && manifest.digests[slug] === digests[slug]
+        ? await forms.of(manifest, slug)
+        : await forms.ofIndex(slug, digests[slug]);
+    if (!found.ok) return { ok: false, message: found.message };
+    if (!found.amd64) {
+      return {
+        ok: false,
+        message: `the ${slug} image index ${digests[slug]} lists no single linux/amd64 manifest`,
+      };
+    }
+    out[slug] = found.amd64;
+  }
+  const { admin, gateway } = out;
+  return admin && gateway
+    ? { ok: true, platformDigests: { admin, gateway } }
+    : { ok: false, message: "the platform digests could not be read" };
+}