@caelo-cms/provisioning 0.10.49 → 0.10.51

package/src/gcp-url-map.test.ts

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #587 — the `gcp` stack's URL map under Pulumi mocks: host routing, the
+ * public path matcher the admin writes redirect rules into, the field the
+ * stack ignores after creation; the admin's custom role is the CLI's.
+ */
+
+import { beforeAll, describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { GCP_PUBLIC_BASE_PATHS, isGcpRedirectRule, withGcpRedirects } from "@caelo-cms/shared";
+import * as pulumi from "@pulumi/pulumi";
+import { URL_MAP_REDIRECTS_PERMISSIONS, urlMapRedirectsRoleId } from "./gcp-names.js";
+
+interface Registered {
+  readonly type: string;
+  readonly name: string;
+  readonly inputs: Record<string, unknown>;
+}
+const registered: Registered[] = [];
+
+beforeAll(() => {
+  pulumi.runtime.setMocks(
+    {
+      newResource: (args) => {
+        registered.push({ type: args.type, name: args.name, inputs: args.inputs });
+        return { id: `${args.name}-id`, state: args.inputs };
+      },
+      call: (args) => args.inputs,
+    },
+    "caelo",
+    "production",
+    false,
+  );
+});
+
+const resolved = <T>(o: pulumi.Output<T>): Promise<T> => new Promise((r) => o.apply(r));
+
+describe("gcp stack URL map (Pulumi mocks)", () => {
+  it("routes the site host to the bucket with /api/* to the gateway, the admin host to the admin", async () => {
+    // Imported after setMocks so the resource registers against the mock monitor.
+    const { createSiteUrlMap, PUBLIC_PATH_MATCHER } = await import("./gcp-url-map.js");
+    const map = createSiteUrlMap(
+      "caelo-production-url-map",
+      {
+        domain: "example.com",
+        adminDomain: "admin.example.com",
+        staticBackend: "bucket-id",
+        gatewayBackend: "gateway-id",
+        adminBackend: "admin-id",
+      },
+      {},
+    );
+    const [hostRules, pathMatchers, defaultService] = await Promise.all([
+      resolved(map.hostRules),
+      resolved(map.pathMatchers),
+      resolved(map.defaultService),
+    ]);
+    expect(defaultService).toBe("bucket-id");
+    expect(hostRules).toEqual([
+      { hosts: ["example.com"], pathMatcher: PUBLIC_PATH_MATCHER },
+      { hosts: ["admin.example.com"], pathMatcher: "admin" },
+    ]);
+    expect(pathMatchers).toEqual([
+      {
+        name: PUBLIC_PATH_MATCHER,
+        defaultService: "bucket-id",
+        pathRules: [{ paths: [...GCP_PUBLIC_BASE_PATHS], service: "gateway-id" }],
+      },
+      { name: "admin", defaultService: "admin-id" },
+    ]);
+    expect(registered.find((r) => r.name === "caelo-production-url-map")?.type).toBe(
+      "gcp:compute/uRLMap:URLMap",
+    );
+
+    // The rules the admin writes on Confirm-publish fit this matcher and keep
+    // its routing — the base the Stage-time budget check assumes.
+    const first = pathMatchers?.[0];
+    if (!first) throw new Error("no public path matcher");
+    const withRedirects = withGcpRedirects(
+      {
+        name: first.name,
+        pathRules: (first.pathRules ?? []).map((r) => ({
+          paths: r.paths ?? [],
+          service: r.service ?? "",
+        })),
+      },
+      {
+        redirects: [
+          {
+            fromPath: "/old",
+            matchPaths: ["/old", "/old/"],
+            location: "/new/",
+            statusCode: 301,
+            preserveQuery: true,
+          },
+        ],
+        gone: [],
+        shadowedByBuild: [],
+      },
+    );
+    expect(withRedirects.pathRules?.filter((r) => !isGcpRedirectRule(r))).toEqual([
+      { paths: ["/api/*"], service: "gateway-id" },
+    ]);
+  });
+
+  it("ignores the public path matcher's path rules after creation (the admin owns the redirects)", async () => {
+    const { SITE_URL_MAP_IGNORE_CHANGES, siteUrlMapArgs, PUBLIC_PATH_MATCHER } = await import(
+      "./gcp-url-map.js"
+    );
+    expect(SITE_URL_MAP_IGNORE_CHANGES).toEqual(["pathMatchers[0].pathRules"]);
+    const args = siteUrlMapArgs({
+      domain: "d",
+      adminDomain: "a.d",
+      staticBackend: "s",
+      gatewayBackend: "g",
+      adminBackend: "a",
+    });
+    // Index 0 must stay the public matcher, or the ignore would hit the admin's.
+    expect((args.pathMatchers as { name: string }[])[0]?.name).toBe(PUBLIC_PATH_MATCHER);
+  });
+});
+
+describe("gcp stack wiring (source)", () => {
+  const src = readFileSync(resolve(import.meta.dir, "../stacks/gcp/index.ts"), "utf8");
+
+  it("builds the URL map through createSiteUrlMap", () => {
+    expect(src).toMatch(/const urlMap = createSiteUrlMap\(\s*`\$\{namePrefix\}-url-map`/);
+    expect(src).not.toMatch(/new gcp\.compute\.URLMap\(\s*`\$\{namePrefix\}-url-map`/);
+  });
+
+  it("leaves the admin's URL-map redirects role to the CLI (installer + upgrade)", () => {
+    expect(src).not.toContain("IAMCustomRole");
+    expect(src).not.toContain("urlMapRedirects");
+  });
+
+  it("names a valid custom role id with only the permissions the writer needs", () => {
+    expect(urlMapRedirectsRoleId("production")).toBe("caelo_production_urlMapRedirects");
+    expect(urlMapRedirectsRoleId("production")).toMatch(/^[A-Za-z0-9_.]{3,64}$/);
+    expect([...URL_MAP_REDIRECTS_PERMISSIONS].sort()).toEqual([
+      "compute.backendBuckets.use",
+      "compute.backendServices.use",
+      "compute.globalOperations.get",
+      "compute.urlMaps.get",
+      "compute.urlMaps.list",
+      "compute.urlMaps.update",
+    ]);
+  });
+});

package/src/gcp-url-map.ts

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The `gcp` stack's URL map, and who may write its redirect rules (#587).
+ *
+ * The admin writes the redirects table into the site host's path matcher
+ * as `urlRedirect` path rules on every Confirm-publish (admin-core
+ * deploy/gcp-url-map-redirects.ts). Those rules change at runtime, not with
+ * `pulumi up`, so the stack must not own them: the URL map ignores changes
+ * to the public path matcher's `pathRules` after creation. Otherwise a
+ * `pulumi refresh` + `up` would wipe every redirect until the next publish.
+ * The admin's writer keeps every non-redirect rule (`/api/*`) as it finds
+ * it.
+ *
+ * The admin's run SA gets a project custom role with only the permissions
+ * that read-modify-write needs (`URL_MAP_REDIRECTS_PERMISSIONS`, gcp-names.ts);
+ * the CLI creates it (url-map-redirects-access.ts), not the stack.
+ *
+ * Imported by the stack from `dist/`; keep it free of CLI dependencies.
+ */
+
+import { GCP_PUBLIC_BASE_PATHS } from "@caelo-cms/shared";
+import * as gcp from "@pulumi/gcp";
+import type * as pulumi from "@pulumi/pulumi";
+
+/** Name of the site host's path matcher. */
+export const PUBLIC_PATH_MATCHER = "public";
+
+/**
+ * The URL map's `ignoreChanges`: the public path matcher (index 0, see
+ * {@link siteUrlMapArgs}) holds the admin-managed redirect rules.
+ */
+export const SITE_URL_MAP_IGNORE_CHANGES: readonly string[] = ["pathMatchers[0].pathRules"];
+
+/** Inputs of {@link siteUrlMapArgs}. */
+export interface SiteUrlMapInputs {
+  readonly domain: string;
+  readonly adminDomain: string;
+  readonly staticBackend: pulumi.Input<string>;
+  readonly gatewayBackend: pulumi.Input<string>;
+  readonly adminBackend: pulumi.Input<string>;
+}
+
+/**
+ * The URL map's arguments: the site host to the static bucket with `/api/*`
+ * to the gateway; the admin host to the IAP-gated admin. The public path
+ * matcher comes first — {@link SITE_URL_MAP_IGNORE_CHANGES} addresses it by
+ * index.
+ */
+export function siteUrlMapArgs(i: SiteUrlMapInputs): gcp.compute.URLMapArgs {
+  return {
+    defaultService: i.staticBackend,
+    hostRules: [
+      { hosts: [i.domain], pathMatcher: PUBLIC_PATH_MATCHER },
+      { hosts: [i.adminDomain], pathMatcher: "admin" },
+    ],
+    pathMatchers: [
+      {
+        name: PUBLIC_PATH_MATCHER,
+        defaultService: i.staticBackend,
+        pathRules: [{ paths: [...GCP_PUBLIC_BASE_PATHS], service: i.gatewayBackend }],
+      },
+      {
+        name: "admin",
+        defaultService: i.adminBackend,
+      },
+    ],
+  };
+}
+
+/** The stack's URL map (see the module comment for the ignored field). */
+export function createSiteUrlMap(
+  name: string,
+  inputs: SiteUrlMapInputs,
+  opts: pulumi.CustomResourceOptions,
+): gcp.compute.URLMap {
+  return new gcp.compute.URLMap(name, siteUrlMapArgs(inputs), {
+    ...opts,
+    ignoreChanges: [...(opts.ignoreChanges ?? []), ...SITE_URL_MAP_IGNORE_CHANGES],
+  });
+}

package/src/index.test.ts

@@ -8,12 +8,6 @@ import { generateBootstrapToken } from "./bootstrap-token.js";
 import { generateCaddyfile } from "./caddy.js";
 import { loadCdnCopyAdapter, selfHostedCdnCopy } from "./cdn-copy.js";
 import { generateDockerCompose } from "./compose.js";
-import {
-  emitRedirectsAzureFrontDoor,
-  emitRedirectsCloudFront,
-  emitRedirectsCloudflare,
-  type RedirectRow,
-} from "./redirects-emit.js";
 
 describe("Caddyfile generator", () => {
   it("emits a vhost per domain + email block", () => {
@@ -21,8 +15,9 @@ describe("Caddyfile generator", () => {
       ownerEmail: "owner@example.com",
       publicSiteRoot: "/srv/caelo/output/production/current",
       stagingSiteRoot: "/srv/caelo/output/staging/current",
-      adminPort: 5173,
-      gatewayPort: 8090,
+      tls: "acme",
+      adminUpstream: "caelo-admin:5173",
+      gatewayUpstream: "caelo-gateway:8090",
       domains: [
         { hostname: "example.com", kind: "public", env: "production" },
         { hostname: "staging.example.com", kind: "public", env: "staging" },
@@ -47,12 +42,13 @@ describe("Caddyfile generator", () => {
       ownerEmail: "x@y.z",
       publicSiteRoot: "/srv/caelo/output/production/current",
       stagingSiteRoot: "/srv/caelo/output/staging/current",
-      adminPort: 5173,
-      gatewayPort: 8090,
+      tls: "acme",
+      adminUpstream: "caelo-admin:5173",
+      gatewayUpstream: "caelo-gateway:8090",
       domains: [],
     });
     expect(out).toContain(":8081 {");
-    expect(out).toContain("reverse_proxy localhost:5173");
+    expect(out).toContain("reverse_proxy caelo-admin:5173");
   });
 });
 
@@ -61,8 +57,9 @@ describe("Caddy cache policy for content-hashed assets", () => {
     ownerEmail: "owner@example.com",
     publicSiteRoot: "/srv/caelo/output/production/current",
     stagingSiteRoot: "/srv/caelo/output/staging/current",
-    adminPort: 5173,
-    gatewayPort: 8090,
+    tls: "acme",
+    adminUpstream: "caelo-admin:5173",
+    gatewayUpstream: "caelo-gateway:8090",
     domains: [
       { hostname: "example.com", kind: "public", env: "production" },
       { hostname: "admin.example.com", kind: "admin", env: "production" },
@@ -119,43 +116,42 @@ describe("docker-compose generator", () => {
       domain: "example.com",
       postgresPassword: "supersecret",
       rolePasswords: { admin: "adminpw", public: "publicpw", gateway: "gatewaypw" },
-      minioRootUser: "caelo",
-      minioRootPassword: "miniopass",
       caeloSecretKek: "0".repeat(64),
       anthropicApiKey: "sk-ant-…",
       diskSize: "20Gi",
       images: RELEASE_IMAGES,
+      ports: { http: 80, https: 443 },
+      project: "caelo-example-com",
     });
-    expect(out).toContain("caelo-postgres");
-    expect(out).toContain("caelo-caddy");
+    expect(out).toContain("  postgres:\n");
+    expect(out).toContain("  caddy:\n");
     expect(out).toContain("caelo-admin");
     expect(out).toContain("caelo-gateway");
     expect(out).toContain("supersecret");
-    expect(out).toContain("miniopass");
     expect(out).toContain("ANTHROPIC_API_KEY");
     expect(out).toContain("CAELO_SECRET_KEK");
   });
 
-  it("gives the gateway gateway_role + public_role and no admin credential (#613)", () => {
+  it("gives the gateway public_role only and no cms_admin credential (#613, #635)", () => {
     const out = generateDockerCompose({
       domain: "example.com",
       postgresPassword: "supersecret",
       rolePasswords: { admin: "adminpw", public: "publicpw", gateway: "gatewaypw" },
-      minioRootUser: "caelo",
-      minioRootPassword: "miniopass",
       caeloSecretKek: "0".repeat(64),
       diskSize: "20Gi",
       images: RELEASE_IMAGES,
+      ports: { http: 80, https: 443 },
+      project: "caelo-example-com",
     });
     const gateway = out.slice(out.indexOf("caelo-gateway:"), out.indexOf("\nvolumes:"));
-    expect(gateway).toContain(
-      'GATEWAY_DATABASE_URL: "postgres://gateway_role:gatewaypw@postgres:5432/cms_admin"',
-    );
     expect(gateway).toContain(
       'PUBLIC_DATABASE_URL: "postgres://public_role:publicpw@postgres:5432/cms_public"',
     );
-    expect(gateway).not.toMatch(/ADMIN_DATABASE|admin_role|adminpw|supersecret|CAELO_SECRET_KEK/);
-    // bootstrap.sh creates the three roles from these.
+    expect(gateway).not.toMatch(
+      /ADMIN_DATABASE|GATEWAY_DATABASE|cms_admin|admin_role|gateway_role|adminpw|gatewaypw|supersecret|CAELO_SECRET_KEK/,
+    );
+    // bootstrap.sh still creates the three roles from these (gateway_role
+    // until the contract release drops it).
     expect(out).toContain('GATEWAY_ROLE_PASSWORD: "gatewaypw"');
   });
 
@@ -164,11 +160,11 @@ describe("docker-compose generator", () => {
       domain: "example.com",
       postgresPassword: 'pa"ss',
       rolePasswords: { admin: "a", public: "b", gateway: "g" },
-      minioRootUser: "caelo",
-      minioRootPassword: "x",
       caeloSecretKek: "0".repeat(64),
       diskSize: "1Gi",
       images: RELEASE_IMAGES,
+      ports: { http: 80, https: 443 },
+      project: "caelo-example-com",
     });
     expect(out).toContain('pa\\"ss');
   });
@@ -190,130 +186,6 @@ describe("bootstrap token generator", () => {
   });
 });
 
-describe("redirects-emit", () => {
-  const rows: RedirectRow[] = [
-    { fromPath: "/old", toPath: "/new", statusCode: 301 },
-    { fromPath: "/blog/2024", toPath: "/blog", statusCode: 302 },
-    { fromPath: "/legacy", toPath: "/modern", statusCode: 308 },
-  ];
-
-  describe("emitRedirectsCloudflare", () => {
-    it("emits one line per row in `<from> <to> <status>` format", () => {
-      const out = emitRedirectsCloudflare(rows);
-      expect(out).toContain("/old /new 301\n");
-      expect(out).toContain("/blog/2024 /blog 302\n");
-      expect(out).toContain("/legacy /modern 308\n");
-      expect(out.startsWith("# Generated by @caelo-cms/provisioning")).toBe(true);
-    });
-
-    it("empty rows → header only, no trailing newline noise", () => {
-      const out = emitRedirectsCloudflare([]);
-      expect(out).toBe("# Generated by @caelo-cms/provisioning — do not edit by hand.\n");
-    });
-
-    it("is byte-identical for the same input (deterministic)", () => {
-      expect(emitRedirectsCloudflare(rows)).toBe(emitRedirectsCloudflare([...rows]));
-    });
-  });
-
-  describe("emitRedirectsCloudFront", () => {
-    it("returns parseable JSON config + a Lambda source that consumes it", () => {
-      const out = emitRedirectsCloudFront(rows);
-      const parsed = JSON.parse(out.jsonConfig) as {
-        redirects: Array<{ from: string; to: string; status: number }>;
-      };
-      expect(parsed.redirects).toHaveLength(3);
-      expect(parsed.redirects[0]).toEqual({ from: "/old", to: "/new", status: 301 });
-      expect(out.lambdaSource).toContain("exports.handler");
-      expect(out.lambdaSource).toContain('require("./redirects.json")');
-    });
-
-    it("preserves status codes verbatim (301/302/307/308)", () => {
-      const allStatuses: RedirectRow[] = [
-        { fromPath: "/a", toPath: "/x", statusCode: 301 },
-        { fromPath: "/b", toPath: "/x", statusCode: 302 },
-        { fromPath: "/c", toPath: "/x", statusCode: 307 },
-        { fromPath: "/d", toPath: "/x", statusCode: 308 },
-      ];
-      const out = emitRedirectsCloudFront(allStatuses);
-      const parsed = JSON.parse(out.jsonConfig) as {
-        redirects: Array<{ status: number }>;
-      };
-      expect(parsed.redirects.map((r) => r.status)).toEqual([301, 302, 307, 308]);
-    });
-  });
-
-  describe("emitRedirectsAzureFrontDoor", () => {
-    it("emits one rule per row with monotonically-increasing order", () => {
-      const out = emitRedirectsAzureFrontDoor(rows);
-      expect(out).toHaveLength(3);
-      expect(out[0]?.name).toBe("redirect-1");
-      expect(out[0]?.order).toBe(1);
-      expect(out[2]?.order).toBe(3);
-    });
-
-    it("maps status codes to Front Door redirectType vocabulary", () => {
-      const out = emitRedirectsAzureFrontDoor([
-        { fromPath: "/a", toPath: "/x", statusCode: 301 },
-        { fromPath: "/b", toPath: "/x", statusCode: 302 },
-        { fromPath: "/c", toPath: "/x", statusCode: 307 },
-        { fromPath: "/d", toPath: "/x", statusCode: 308 },
-      ]);
-      expect(out.map((r) => r.actions[0]?.parameters.redirectType)).toEqual([
-        "Moved",
-        "Found",
-        "TemporaryRedirect",
-        "PermanentRedirect",
-      ]);
-    });
-
-    it("RequestUri condition matches the from path exactly", () => {
-      const out = emitRedirectsAzureFrontDoor(rows);
-      expect(out[1]?.conditions[0]?.parameters.matchValues).toEqual(["/blog/2024"]);
-      expect(out[1]?.actions[0]?.parameters.destinationPath).toBe("/blog");
-    });
-  });
-
-  describe("path-validation guard (review-pass #9)", () => {
-    it("Cloudflare emitter rejects fromPath with whitespace", () => {
-      expect(() =>
-        emitRedirectsCloudflare([{ fromPath: "/old path", toPath: "/new", statusCode: 301 }]),
-      ).toThrow(/contains whitespace/);
-    });
-
-    it("CloudFront emitter rejects toPath with newline", () => {
-      expect(() =>
-        emitRedirectsCloudFront([{ fromPath: "/old", toPath: "/new\nlies", statusCode: 301 }]),
-      ).toThrow(/contains whitespace/);
-    });
-
-    it("every emitter rejects an off-site or URL-embedding toPath (#657)", () => {
-      for (const toPath of ["//evil.example/x", "/https://example.com/x"]) {
-        const rows = [{ fromPath: "/old", toPath, statusCode: 301 as const }];
-        expect(() => emitRedirectsCloudflare(rows)).toThrow(/redirects-emit: toPath/);
-        expect(() => emitRedirectsCloudFront(rows)).toThrow(/redirects-emit: toPath/);
-        expect(() => emitRedirectsAzureFrontDoor(rows)).toThrow(/redirects-emit: toPath/);
-      }
-    });
-
-    it("Azure emitter rejects tab in path", () => {
-      expect(() =>
-        emitRedirectsAzureFrontDoor([{ fromPath: "/old\there", toPath: "/x", statusCode: 301 }]),
-      ).toThrow(/contains whitespace/);
-    });
-
-    it("hyphens, dots, slashes, unicode in path segments are accepted", () => {
-      // Regression guard for the original buggy regex `[\s -]` which
-      // rejected hyphens.
-      expect(() =>
-        emitRedirectsCloudflare([
-          { fromPath: "/blog/spring-launch", toPath: "/blog/sommer-2026", statusCode: 301 },
-        ]),
-      ).not.toThrow();
-    });
-  });
-});
-
 describe("cdn-copy adapter loader", () => {
   it("returns the no-op self-hosted adapter when provider is unset/empty/self-hosted", async () => {
     expect(await loadCdnCopyAdapter(undefined)).toBe(selfHostedCdnCopy);

package/src/index.ts

@@ -47,15 +47,6 @@ export {
 } from "./cdn-copy.js";
 export { type ComposeSpec, generateDockerCompose, type RolePasswords } from "./compose.js";
 export { INFRA_CONTRACT_VERSION } from "./infra-contract.js";
-export {
-  type CloudFrontRedirectArtifact,
-  emitRedirectsAzureFrontDoor,
-  emitRedirectsCloudFront,
-  emitRedirectsCloudflare,
-  type FrontDoorRule,
-  type RedirectRow,
-  type RedirectStatusCode,
-} from "./redirects-emit.js";
 export {
   INFRA_CONTRACT_PATHS,
   isInfraContractPath,

package/src/infra-contract.test.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Every infrastructure contract version names the step it adds, so the
+ * upgrader's refusal tells the Owner what the Cloud Shell run will change.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  INFRA_CONTRACT_STEPS,
+  INFRA_CONTRACT_VERSION,
+  infraStepsText,
+  pendingInfraSteps,
+} from "./infra-contract.js";
+
+describe("infrastructure contract steps", () => {
+  it("describes every version up to the current one, and no other", () => {
+    expect(Object.keys(INFRA_CONTRACT_STEPS).map(Number)).toEqual(
+      Array.from({ length: INFRA_CONTRACT_VERSION }, (_, i) => i + 1),
+    );
+  });
+
+  it("is at 5: public_role revoke (3), URL-map redirects role (4), no gateway cms_admin login (5)", () => {
+    expect(INFRA_CONTRACT_VERSION).toBe(5);
+    expect(INFRA_CONTRACT_STEPS[3]).toContain("#633");
+    expect(INFRA_CONTRACT_STEPS[4]).toContain("#587");
+    expect(INFRA_CONTRACT_STEPS[5]).toContain("#635");
+  });
+
+  it("lists the pending steps oldest first", () => {
+    expect(pendingInfraSteps(2, 4)).toEqual([INFRA_CONTRACT_STEPS[3], INFRA_CONTRACT_STEPS[4]]);
+    expect(pendingInfraSteps(3, 4)).toEqual([INFRA_CONTRACT_STEPS[4]]);
+    expect(pendingInfraSteps(4, 4)).toEqual([]);
+    expect(pendingInfraSteps(0, 1)).toEqual([INFRA_CONTRACT_STEPS[1]]);
+  });
+
+  it("names a version a newer release added by number", () => {
+    expect(infraStepsText(5, 6)).toBe("infrastructure step 6 (see that release's notes)");
+  });
+});

package/src/infra-contract.ts

@@ -22,7 +22,7 @@
  * whose app-roll references infrastructure an install does not have yet fails
  * at roll time, after migrations ran.
  */
-export const INFRA_CONTRACT_VERSION = 2;
+export const INFRA_CONTRACT_VERSION = 5;
 
 // History (why each bump happened — an install below a number needs the
 // converge that introduced it):
@@ -30,3 +30,49 @@ export const INFRA_CONTRACT_VERSION = 2;
 //   2 — the upgrader job (#696 Phase 2): its service account + scoped
 //       grants, the Cloud SQL backup role, its IAM database user, the job,
 //       the admin's run-only grant and CAELO_UPGRADER_JOB on the admin.
+//   3 — public_role out of cloudsqlsuperuser (#633): the Admin API revoke
+//       runs as the operator; migration 0278's role audit refuses an install
+//       that has not had it, so the in-cloud upgrader must not get there
+//       first.
+//   4 — #587: on `gcp`, the admin's custom role for writing the redirects
+//       table into the URL map (url-map-redirects-access.ts).
+//   5 — #635: the gateway has no cms_admin login. Its GATEWAY_DATABASE_URL /
+//       GATEWAY_DATABASE_PASSWORD go, and its SA loses access to the
+//       gateway-role-password secret (a retired IAM binding, removed after
+//       the roll — the in-cloud upgrader cannot change IAM).
+
+/**
+ * What each contract version adds, in operator terms — the upgrader's
+ * refusal names the steps an install is missing. Keep one entry per version
+ * (the history above says why each bump happened).
+ */
+export const INFRA_CONTRACT_STEPS: Readonly<Record<number, string>> = {
+  1: "the converge/app-roll split",
+  2: "the in-cloud upgrader job and its scoped permissions",
+  3: "public_role out of the Cloud SQL superuser group (#633)",
+  4: "the admin's permission to serve redirects from the load balancer (#587)",
+  5: "the gateway's cms_admin login removed from its env and IAM (#635)",
+};
+
+/**
+ * The steps an install at contract `installed` lacks for `target`, oldest
+ * first. A release newer than this code can carry versions it does not know
+ * (the upgrader reads the NEW release's manifest); those are named by number.
+ *
+ * @example
+ *   pendingInfraSteps(2, 4)
+ *   // → ["public_role out of the Cloud SQL superuser group (#633)",
+ *   //    "the admin's permission to serve redirects from the load balancer (#587)"]
+ */
+export function pendingInfraSteps(installed: number, target: number): string[] {
+  const steps: string[] = [];
+  for (let v = Math.max(installed, 0) + 1; v <= target; v += 1) {
+    steps.push(INFRA_CONTRACT_STEPS[v] ?? `infrastructure step ${v} (see that release's notes)`);
+  }
+  return steps;
+}
+
+/** {@link pendingInfraSteps} as one sentence fragment for messages. */
+export function infraStepsText(installed: number, target: number): string {
+  return pendingInfraSteps(installed, target).join("; ");
+}