@caelo-cms/provisioning 0.10.64 → 0.10.66

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" };
+}

package/src/upgrade/release-images.ts

@@ -167,6 +167,55 @@ export async function resolveRegistryDigest(
   }
 }
 
+/** What {@link fetchRegistryManifest} read. */
+export type RegistryManifestResult =
+  | { readonly ok: true; readonly bytes: Uint8Array<ArrayBuffer> }
+  | {
+      readonly ok: false;
+      /**
+       * True when a retry may cure it: the registry could not be reached,
+       * timed out, rate-limited (429/408), failed (5xx) or would not hand
+       * out a pull token. False when it answered that the manifest does not
+       * exist (404 and other 4xx).
+       */
+      readonly transient: boolean;
+      readonly reason: string;
+    };
+
+/**
+ * GET the manifest (or index) `<registryHost>/<repository>@<reference>`
+ * anonymously, through the same Bearer-challenge handling as
+ * {@link resolveRegistryDigest}. Returns the raw bytes: a caller that asked
+ * by digest checks them against it (content addressing is the trust here).
+ *
+ * @example fetchRegistryManifest("europe-west1-docker.pkg.dev", "caelo-website/caelo-cms-images/admin", "sha256:…")
+ */
+export async function fetchRegistryManifest(
+  registryHost: string,
+  repository: string,
+  reference: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<RegistryManifestResult> {
+  const url = `https://${registryHost}/v2/${repository}/manifests/${reference}`;
+  try {
+    let res = await fetchImpl(url, { headers: { Accept: MANIFEST_ACCEPT } });
+    if (res.status === 401) {
+      const token = await anonymousPullToken(res.headers.get("www-authenticate"), fetchImpl);
+      if (!token.ok) return { ok: false, transient: true, reason: token.reason };
+      res = await fetchImpl(url, {
+        headers: { Accept: MANIFEST_ACCEPT, Authorization: `Bearer ${token.token}` },
+      });
+    }
+    if (!res.ok) {
+      const transient = res.status >= 500 || res.status === 429 || res.status === 408;
+      return { ok: false, transient, reason: `${url}: HTTP ${res.status} ${res.statusText}` };
+    }
+    return { ok: true, bytes: new Uint8Array(await res.arrayBuffer()) };
+  } catch (e) {
+    return { ok: false, transient: true, reason: e instanceof Error ? e.message : String(e) };
+  }
+}
+
 /** Follow a registry's Bearer challenge to an anonymous pull token. */
 async function anonymousPullToken(
   challenge: string | null,

package/src/upgrader-gcp.ts

@@ -28,6 +28,7 @@ import { acquireBucketStateLock, GcsStateStore, realSyncGcloud } from "./state-s
 import type { AppRollPlan } from "./upgrade/app-roll.js";
 import { findServiceUrl } from "./upgrade/gcp-lookup.js";
 import { createIapHealthProbe } from "./upgrade/health.js";
+import { createReleaseImageForms } from "./upgrade/image-forms.js";
 import { type IamTester, restIamTester } from "./upgrader-iam-preflight.js";
 import type { UpdateQueue, UpgraderJobDeps } from "./upgrader-job.js";
 import type { JobLog } from "./upgrader-reporter.js";
@@ -134,6 +135,8 @@ export function gcpUpgraderDeps(
     iam: gcloudIamTester(run, http),
     // The default deps: the fixed registry and signer, never overridden.
     fetchManifest: (version) => fetchVerifiedReleaseManifest(version),
+    // #1025 — the fixed public mirror, read by digest and content-checked.
+    imageForms: createReleaseImageForms(),
     // #815 — the lock names this execution, so a later run can break it
     // once Cloud Run says this one has ended (killed at its task timeout,
     // OOM). Outside Cloud Run there is no execution to vouch for it.

package/src/upgrader-job.test.ts

@@ -15,7 +15,19 @@ import type { GcloudRunner } from "./gcloud-retry.js";
 import type { InstallMetadata } from "./install-state.js";
 import type { ReleaseManifest, ReleaseManifestResult } from "./release-manifest.js";
 import { StateLockHeldError } from "./state-store.js";
+import {
+  ADMIN_AMD64,
+  ADMIN_INDEX,
+  fakeRegistryFetch,
+  GATEWAY_AMD64,
+  GATEWAY_INDEX,
+} from "./upgrade/__tests__/live-indexes.js";
 import type { HealthOutcome, HealthProbe } from "./upgrade/health.js";
+import {
+  createReleaseImageForms,
+  type ImageFormsResult,
+  type ReleaseImageForms,
+} from "./upgrade/image-forms.js";
 import { type IamTester, resourceName } from "./upgrader-iam-preflight.js";
 import {
   type ClaimedUpdate,
@@ -212,6 +224,11 @@ function setup(
     lockDenied?: boolean;
     /** The lock broke a dead run's lock on the way, with this message. */
     brokeStaleLock?: string;
+    /**
+     * The release mirror (#1025): by default index `D(c)` lists platform
+     * manifest `P(c)`; `down` makes every index read fail as an outage.
+     */
+    imageForms?: ReleaseImageForms | "down";
     /** IAM's answer: permissions withheld per resource name. */
     iamWithheld?: Record<string, readonly string[]>;
     /** A resource IAM cannot be asked about. */
@@ -246,6 +263,10 @@ function setup(
       }
       return opts.manifest ?? { ok: true, manifest: MANIFEST };
     },
+    imageForms:
+      typeof opts.imageForms === "object"
+        ? opts.imageForms
+        : fakeImageForms(order, opts.imageForms === "down"),
     lockState: (onBreak) => {
       order.push("lock");
       if (opts.locked) throw new StateLockHeldError("held by caelo installer");
@@ -271,6 +292,28 @@ function setup(
   return { deps, order, q, written };
 }
 
+/**
+ * The release mirror's indexes as {@link ReleaseImageForms}: index `D(c)`
+ * lists platform manifest `P(c)` (#1025). Signed platform digests win, as
+ * in createReleaseImageForms.
+ */
+function fakeImageForms(order: string[], down: boolean): ReleaseImageForms {
+  const ofIndex = async (slug: string, index: string): Promise<ImageFormsResult> => {
+    order.push(`index ${slug}@${index}`);
+    if (down) return { ok: false, transient: true, message: "the mirror answered HTTP 503" };
+    const platform = P(index.slice(-1));
+    return { ok: true, digests: [index, platform], amd64: platform };
+  };
+  return {
+    ofIndex,
+    of: async (m, slug) => {
+      const signed = m.platformDigests?.[slug];
+      if (signed) return { ok: true, digests: [m.digests[slug], signed], amd64: signed };
+      return ofIndex(slug, m.digests[slug]);
+    },
+  };
+}
+
 /** IAM granting everything asked except `withheld` per resource; `error` names a resource it cannot be asked about. */
 function fakeIam(
   order: string[],
@@ -765,6 +808,116 @@ describe("runUpgraderJob", () => {
     expect(order).not.toContain("manifest 0.11.0");
   });
 
+  describe("regression #1025: Cloud Run's revision spec names the platform manifest", () => {
+    /** Serving revisions whose spec AND status name only the platform digests (the live shape). */
+    const servingPlatform = (admin: string, gateway: string): [RegExp, Answer] => [
+      /^run revisions describe (\S+)/,
+      (l) => {
+        const d = l.includes("-admin-") ? admin : gateway;
+        return ok(revisionJson(d, d));
+      },
+    ];
+
+    it("the live v0.10.64 shapes: identified by the signed indexes, records both forms, installs", async () => {
+      const calls: string[] = [];
+      const v064 = {
+        ...MANIFEST,
+        version: "0.10.64",
+        digests: { admin: ADMIN_INDEX, gateway: GATEWAY_INDEX, ops: D("c") },
+      };
+      const { deps, q, written } = setup({
+        meta: {
+          ...META,
+          imageDigests: { admin: ADMIN_INDEX, gateway: GATEWAY_INDEX },
+          releaseVersion: "0.10.64",
+        },
+        manifests: { "0.10.64": { ok: true, manifest: v064 } },
+        gcloud: [servingPlatform(ADMIN_AMD64, GATEWAY_AMD64)],
+        imageForms: createReleaseImageForms(fakeRegistryFetch(calls)),
+      });
+      expect((await runUpgraderJob(deps)).status).toBe("succeeded");
+      expect(written[0]).toMatchObject({
+        releaseVersion: "0.10.64",
+        imageDigests: { admin: ADMIN_INDEX, gateway: GATEWAY_INDEX },
+        platformDigests: { admin: ADMIN_AMD64, gateway: GATEWAY_AMD64 },
+      });
+      expect(q.events.some((e) => e.message.startsWith("0.10.64 → 0.11.0"))).toBe(true);
+      // Each index read once, by digest, from the fixed mirror.
+      expect(calls.filter((c) => c.endsWith(`/admin/manifests/${ADMIN_INDEX}`))).toHaveLength(1);
+      expect(calls.filter((c) => c.endsWith(`/gateway/manifests/${GATEWAY_INDEX}`))).toHaveLength(
+        1,
+      );
+    });
+
+    it("install.json with both forms matches directly: no drift, no lookup", async () => {
+      const { deps, order, q } = setup({
+        meta: { ...META, platformDigests: { admin: P("1"), gateway: P("2") } },
+        gcloud: [servingPlatform(P("1"), P("2"))],
+      });
+      expect((await runUpgraderJob(deps)).status).toBe("succeeded");
+      expect(order.filter((l) => l.startsWith("manifest"))).toEqual(["manifest 0.11.0"]);
+      // Only the target's index is read (to record its platform forms), never the serving one's.
+      expect(order.filter((l) => l.startsWith("index "))).toEqual([
+        `index admin@${D("a")}`,
+        `index gateway@${D("b")}`,
+      ]);
+      expect(q.events.some((e) => e.message.includes("refreshed its install records"))).toBe(false);
+    });
+
+    it("the roll records the new release's platform forms, signed ones first", async () => {
+      const signed = {
+        ...MANIFEST,
+        platformDigests: { admin: P("x"), gateway: P("y"), ops: P("z") },
+      };
+      const { deps, order, written } = setup({ manifest: { ok: true, manifest: signed } });
+      expect((await runUpgraderJob(deps)).status).toBe("succeeded");
+      expect(written.at(-1)).toMatchObject({
+        releaseVersion: "0.11.0",
+        imageDigests: { admin: D("a"), gateway: D("b") },
+        platformDigests: { admin: P("x"), gateway: P("y") },
+      });
+      expect(order.some((l) => l.startsWith("index "))).toBe(false);
+    });
+
+    it("a stale platform record is dropped when the platform forms cannot be read", async () => {
+      const { deps, q, written } = setup({
+        meta: { ...META, platformDigests: { admin: P("1"), gateway: P("2") } },
+        imageForms: "down",
+      });
+      expect((await runUpgraderJob(deps)).status).toBe("succeeded");
+      expect(written.at(-1)?.imageDigests).toEqual({ admin: D("a"), gateway: D("b") });
+      expect(written.at(-1)?.platformDigests).toBeUndefined();
+      expect(q.events.some((e) => e.level === "warn" && e.message.includes("linux/amd64"))).toBe(
+        true,
+      );
+    });
+
+    it("a platform digest in no signed index is still refused with the current message", async () => {
+      const { deps, q, written } = setup({
+        gcloud: [servingPlatform(P("7"), P("6"))],
+        manifests: { "0.10.45": manifestOf("0.10.45", D("1"), D("2")) },
+      });
+      expect((await runUpgraderJob(deps)).status).toBe("needs_cloud_shell");
+      const end = q.end();
+      expect(end?.codes).toEqual(["install-state-drift"]);
+      expect(end?.reason).toContain("do not belong to one signed Caelo release");
+      expect(end?.reason).toContain(`admin ${P("7")}`);
+      expect(written).toEqual([]);
+    });
+
+    it("an index the mirror cannot serve fails retryably, never as drift", async () => {
+      const { deps, q, written } = setup({
+        gcloud: [servingPlatform(P("1"), P("2"))],
+        manifests: { "0.10.45": manifestOf("0.10.45", D("1"), D("2")) },
+        imageForms: "down",
+      });
+      expect((await runUpgraderJob(deps)).status).toBe("failed");
+      expect(q.end()?.codes).toEqual(["registry"]);
+      expect(q.end()?.reason).toContain("HTTP 503");
+      expect(written).toEqual([]);
+    });
+  });
+
   it("regression #865: drift whose release manifest the registry cannot serve fails retryably, not install-state-drift", async () => {
     const { deps, order, q, written } = setup({
       meta: {