@caelo-cms/provisioning 0.10.55 → 0.10.58

package/src/upgrade/upgrade.test.ts

@@ -23,7 +23,12 @@ import { restoreCommand, takeSqlBackup } from "./backup.js";
 import { needsConverge, startConverge } from "./converge.js";
 import type { HealthOutcome, HealthProbe } from "./health.js";
 import type { UpgradeReporter } from "./reporter.js";
-import { type GcpUpgradeDeps, type GcpUpgradeTarget, upgradeGcpInstall } from "./upgrade.js";
+import {
+  type GcpUpgradeDeps,
+  type GcpUpgradeTarget,
+  upgradeGcpInstall,
+  upgradeGcpInstallOutcome,
+} from "./upgrade.js";
 
 const ok = (stdout = ""): GcloudResult => ({ ok: true, stdout, stderr: "", exitCode: 0 });
 const fail = (stderr: string): GcloudResult => ({ ok: false, stdout: "", stderr, exitCode: 1 });
@@ -460,6 +465,142 @@ describe("upgradeGcpInstall — converge, then app-roll", () => {
     expect(calls.some((c) => c.includes("remove-iam-policy-binding"))).toBe(false);
   });
 
+  it("#883 review: reports rolledBack structurally — true only when every pin back succeeded", async () => {
+    const deep = { ok: false as const, error: "cms_admin is missing 1 migration(s)" };
+    const back = upgradeDeps([], { deep });
+    expect(await upgradeGcpInstallOutcome(TARGET, back.deps)).toEqual({
+      ok: false,
+      rolledBack: true,
+    });
+
+    // The gateway's pin back fails: the previous release does NOT serve.
+    const stuck = upgradeDeps([], {
+      deep,
+      overrides: [[new RegExp(`update-traffic ${GATEWAY} .*--to-revisions`), fail("503")]],
+    });
+    expect(await upgradeGcpInstallOutcome(TARGET, stuck.deps)).toEqual({
+      ok: false,
+      rolledBack: false,
+    });
+
+    // Nothing rolled (migrations failed): no rollback, so not rolled back.
+    const early = upgradeDeps([]);
+    expect(
+      await upgradeGcpInstallOutcome(TARGET, {
+        ...early.deps,
+        migrate: async () => ({ ok: false, error: "boom" }),
+      }),
+    ).toEqual({ ok: false, rolledBack: false });
+
+    expect(await upgradeGcpInstallOutcome(TARGET, upgradeDeps([]).deps)).toEqual({ ok: true });
+  });
+
+  it("sets up the converge job as the install's provisioner after the upgrader (#819)", async () => {
+    const events: string[] = [];
+    const { deps, lines } = upgradeDeps(events);
+    expect(await upgradeGcpInstall(TARGET, deps)).toBe(true);
+    const upgrader = indexOf(events, /^gcloud run jobs deploy caelo-production-upgrader /);
+    const converge = indexOf(events, /^gcloud run jobs deploy caelo-production-converge /);
+    expect(upgrader).toBeLessThan(converge);
+    expect(events[converge]).toContain(
+      "--service-account=caelo-provisioner@acme.iam.gserviceaccount.com",
+    );
+    expect(events[converge]).toContain(`--image=registry/ops@sha256:${"c".repeat(64)}`);
+    expect(lines.some((l) => l.startsWith("done: Converge job ready"))).toBe(true);
+  });
+
+  it("a failed converge-job setup leaves the converge incomplete and CAELO_CONVERGE_JOB as it was", async () => {
+    const events: string[] = [];
+    const { deps, recorded, lines } = upgradeDeps(events, {
+      overrides: [[/^run jobs deploy caelo-production-converge /, fail("PERMISSION_DENIED")]],
+    });
+    expect(await upgradeGcpInstall(TARGET, deps)).toBe(true);
+    expect(recorded.contract).toEqual([]);
+    expect(lines.some((l) => l.includes("Converge job not set up"))).toBe(true);
+    expect(
+      events.some((e) => /services update caelo-production-admin.*CAELO_CONVERGE_JOB=/.test(e)),
+    ).toBe(false);
+  });
+
+  it("#883 review: an install without caelo-provisioner still records the contract; its admin keeps the terminal path", async () => {
+    const events: string[] = [];
+    const { deps, recorded, lines } = upgradeDeps(events, {
+      overrides: [
+        [
+          /^iam service-accounts describe caelo-provisioner@/,
+          fail("ERROR: NOT_FOUND: Unknown service account"),
+        ],
+        // A project without the default network's open rules: nothing
+        // else keeps this converge incomplete.
+        [/^compute firewall-rules list/, ok("[]")],
+      ],
+    });
+    expect(await upgradeGcpInstall(TARGET, deps)).toBe(true);
+    // Not blocked forever: the converge is complete without the job.
+    expect(recorded.contract).toEqual([TARGET.infraContractVersion]);
+    expect(lines.some((l) => l.includes("no caelo-provisioner"))).toBe(true);
+    expect(lines.some((l) => l.includes("Converge job not set up"))).toBe(false);
+    // No job, so no CAELO_CONVERGE_JOB: the admin routes such releases to the terminal.
+    expect(events.some((e) => /^gcloud run jobs deploy caelo-production-converge /.test(e))).toBe(
+      false,
+    );
+    expect(
+      events.some((e) => /services update caelo-production-admin.*CAELO_CONVERGE_JOB=/.test(e)),
+    ).toBe(false);
+  });
+
+  it("reports its backup and rollback targets before relying on them (#819 checkpoint)", async () => {
+    const events: string[] = [];
+    const { deps } = upgradeDeps(events);
+    const seen: string[] = [];
+    expect(
+      await upgradeGcpInstall(TARGET, {
+        ...deps,
+        onCheckpoint: (c) => {
+          if (c.priorRevisions) events.push(`checkpoint revisions ${c.priorRevisions.admin}`);
+          if (c.backup) events.push(`checkpoint backup ${c.backup.backupId}`);
+          seen.push(Object.keys(c).join(","));
+        },
+      }),
+    ).toBe(true);
+    expect(seen).toEqual(["priorRevisions", "backup"]);
+    const revisions = indexOf(events, /^checkpoint revisions caelo-production-admin-aaa-00001-old/);
+    const backup = indexOf(events, /^gcloud sql backups create/);
+    const saved = indexOf(events, new RegExp(`^checkpoint backup ${BACKUP_ID}`));
+    const migrate = indexOf(events, /^migrate /);
+    expect(revisions).toBeLessThan(backup);
+    expect(backup).toBeLessThan(saved);
+    expect(saved).toBeLessThan(migrate);
+  });
+
+  it("a resumed run keeps the interrupted run's backup and rolls back onto what served before it (#819)", async () => {
+    const events: string[] = [];
+    const { deps, lines } = upgradeDeps(events, {
+      deep: { ok: false, error: "unhealthy" },
+    });
+    const before = { admin: `${ADMIN}-00000-before`, gateway: `${GATEWAY}-00000-before` };
+    expect(
+      await upgradeGcpInstall(TARGET, {
+        ...deps,
+        resume: {
+          backup: { projectId: "acme", instance: SQL, backupId: "1759999999999" },
+          priorRevisions: before,
+        },
+        onCheckpoint: () => events.push("checkpoint"),
+      }),
+    ).toBe(false);
+    expect(events.some((e) => /sql backups create/.test(e))).toBe(false);
+    expect(events).not.toContain("checkpoint");
+    expect(lines).toContain(
+      "info: Continuing an interrupted update: keeping its pre-upgrade backup 1759999999999.",
+    );
+    const rollbacks = events.filter((e) => e.includes("--to-revisions"));
+    expect(rollbacks).toEqual([
+      expect.stringContaining(`--to-revisions ${before.gateway}=100`),
+      expect.stringContaining(`--to-revisions ${before.admin}=100`),
+    ]);
+  });
+
   it("revokes public_role's Cloud SQL role memberships before the migrations audit them (#633)", async () => {
     const events: string[] = [];
     const { deps, lines } = upgradeDeps(events);
@@ -527,6 +668,65 @@ describe("upgradeGcpInstall — converge, then app-roll", () => {
     expect(recorded.contract).toEqual([]);
   });
 
+  it("#806 — the rolls carry remote MCP: identity env, the gateway's client file and timeout", async () => {
+    const events: string[] = [];
+    const { deps, calls } = upgradeDeps(events);
+    expect(await upgradeGcpInstall(TARGET, deps)).toBe(true);
+    const rolls = calls.filter((c) =>
+      /^run services update \S+ --region europe-west1 .*--image/.test(c),
+    );
+    const admin = rolls.find((c) => c.startsWith(`run services update ${ADMIN} `)) ?? "";
+    const gateway = rolls.find((c) => c.startsWith(`run services update ${GATEWAY} `)) ?? "";
+    expect(admin).toContain(
+      `CAELO_IAP_AUDIENCE=/projects/42/locations/europe-west1/services/${ADMIN}`,
+    );
+    expect(admin).toContain(`CAELO_MCP_PUBLIC_URL=https://${GATEWAY}-xyz.a.run.app`);
+    expect(gateway).toContain(`CAELO_ADMIN_URL=https://${ADMIN}-xyz.a.run.app`);
+    expect(gateway).toContain(`CAELO_MCP_PUBLIC_URL=https://${GATEWAY}-xyz.a.run.app`);
+    expect(gateway).toContain(
+      "--update-secrets=/secrets/operator-oauth-client/client.json=caelo-production-operator-oauth-client:latest",
+    );
+    expect(gateway).toContain("--timeout=3600");
+    expect(admin).not.toContain("--timeout");
+    // No extra revision: everything rides the image rolls.
+    expect(calls.filter((c) => /^run services update /.test(c))).toHaveLength(2);
+  });
+
+  it("#806 — on gcp, routes the discovery paths and adds the Cloud Armor rule before the roll", async () => {
+    const events: string[] = [];
+    const urlMap = {
+      name: "caelo-production-url-map-1",
+      hostRules: [{ hosts: ["acme.com"], pathMatcher: "public" }],
+      pathMatchers: [{ name: "public", pathRules: [{ paths: ["/api/*"], service: "gw" }] }],
+    };
+    const puts: string[] = [];
+    const { deps, lines } = upgradeDeps(events, {
+      overrides: [
+        [/^compute url-maps list/, ok(JSON.stringify([urlMap]))],
+        [/^compute security-policies list/, ok("caelo-production-waf-1\n")],
+        [/^compute security-policies describe/, ok(JSON.stringify({ rules: [] }))],
+      ],
+    });
+    const recordingHttp: HttpFetch = async (url, init) => {
+      if (init.method === "PUT" && url.includes("/urlMaps/"))
+        puts.push(`${url} ${init.body ?? ""}`);
+      return http(url, init);
+    };
+    expect(await upgradeGcpInstall(GCP_TARGET, { ...deps, http: recordingHttp })).toBe(true);
+    expect(events).toContainEqual(
+      expect.stringMatching(
+        /^gcloud compute security-policies rules create 900 --security-policy=caelo-production-waf-1 /,
+      ),
+    );
+    expect(puts).toHaveLength(1);
+    expect(puts[0]).toContain("/global/urlMaps/caelo-production-url-map-1");
+    expect(puts[0]).toContain("/.well-known/oauth-authorization-server/*");
+    expect(lines).toContain("done: Remote-MCP load-balancer rules ready");
+    expect(indexOf(events, /security-policies rules create/)).toBeLessThan(
+      indexOf(events, /^migrate /),
+    );
+  });
+
   it("on gcp-firebase there is no URL map: no redirects role", async () => {
     const events: string[] = [];
     const { deps, calls } = upgradeDeps(events);
@@ -691,7 +891,7 @@ describe("app-roll and converge stay on their side", () => {
         },
       },
     );
-    expect(result).toEqual({ ok: false, phase: "roll", migrated: true });
+    expect(result).toEqual({ ok: false, phase: "roll", migrated: true, rolledBack: true });
     expect(calls).toContain(
       `run services update-traffic ${ADMIN} --region europe-west1 --project acme --to-revisions ${ADMIN}-00001-old=100 --quiet`,
     );
@@ -715,7 +915,7 @@ describe("app-roll and converge stay on their side", () => {
         recordDigests: async () => {},
       },
     );
-    expect(result).toEqual({ ok: false, phase: "migrations", migrated: true });
+    expect(result).toEqual({ ok: false, phase: "migrations", migrated: true, rolledBack: false });
     expect(calls.filter((c) => APP_ROLL_WRITE.test(c))).toEqual([]);
     expect(
       lines.some((l) => l.includes("contract-type") && l.includes(restoreCommand(BACKUP))),

package/src/upgrade/upgrade.ts

@@ -17,7 +17,14 @@
  *      install's infrastructure contract version
  *
  * Every side effect goes through {@link GcpUpgradeDeps}, so the sequence runs
- * against a fake gcloud in tests. lifecycle.ts wires the real ones.
+ * against a fake gcloud in tests. lifecycle.ts wires the real ones for the
+ * terminal; converge-job-gcp.ts wires them for the converge job (#819),
+ * which runs this same sequence from inside the install's project. The job
+ * may be killed mid-way and started again, so the sequence reports its two
+ * facts a resumed run must not recompute — the pre-upgrade backup and the
+ * revisions that served before ({@link UpgradeCheckpoint}) — and accepts
+ * them back: a resumed run neither backs up the half-migrated database
+ * again nor rolls back onto a revision the interrupted run created.
  */
 
 import type { GcloudRunner, Sleep } from "../gcloud-retry.js";
@@ -31,7 +38,7 @@ import {
   type RollSlug,
   reportPlan,
 } from "./app-roll.js";
-import { backupFailureHelp, restoreCommand, takeSqlBackup } from "./backup.js";
+import { backupFailureHelp, restoreCommand, type SqlBackup, takeSqlBackup } from "./backup.js";
 import { startConverge } from "./converge.js";
 import type { HealthProbe } from "./health.js";
 import type { UpgradeReporter } from "./reporter.js";
@@ -51,6 +58,21 @@ export interface GcpUpgradeTarget {
   readonly infraContractVersion: number;
   readonly skipVerify: boolean;
   readonly skipHealthCheck: boolean;
+  /**
+   * Whether the release's migrations are contract-type, from the signed
+   * release manifest (the converge job knows it; the terminal does not).
+   */
+  readonly migrationsContract?: boolean | null;
+}
+
+/**
+ * What an upgrade run has fixed that a resumed run must reuse (#819): the
+ * backup taken before anything changed, and the revisions that served
+ * before — the rollback targets.
+ */
+export interface UpgradeCheckpoint {
+  readonly backup?: SqlBackup;
+  readonly priorRevisions?: Readonly<Record<RollSlug, string>>;
 }
 
 export interface GcpUpgradeDeps {
@@ -86,13 +108,43 @@ export interface GcpUpgradeDeps {
   readonly provisionerIdentity?: () => Promise<boolean>;
   /** Today, for the backup's description. */
   readonly now?: () => Date;
+  /** #819 — what an interrupted run of this same upgrade already fixed. */
+  readonly resume?: UpgradeCheckpoint;
+  /** #819 — called once each checkpoint fact is known (before it is relied on). */
+  readonly onCheckpoint?: (checkpoint: UpgradeCheckpoint) => void;
 }
 
+/** How {@link upgradeGcpInstallOutcome} ended. */
+export type GcpUpgradeOutcome =
+  | { readonly ok: true }
+  | {
+      readonly ok: false;
+      /**
+       * The roll failed AND every rolled service was pinned back to the
+       * revision that served before (app-roll.ts AppRollResult): the
+       * previous release serves again. Structural, never read from text.
+       */
+      readonly rolledBack: boolean;
+    };
+
 /** Upgrade one install; true on success. See the file comment for the order. */
 export async function upgradeGcpInstall(
   target: GcpUpgradeTarget,
   deps: GcpUpgradeDeps,
 ): Promise<boolean> {
+  return (await upgradeGcpInstallOutcome(target, deps)).ok;
+}
+
+/**
+ * {@link upgradeGcpInstall} with how a failure ended: whether the previous
+ * release serves again after a rollback (the converge job reports
+ * rolled_back only then, #819 review).
+ */
+export async function upgradeGcpInstallOutcome(
+  target: GcpUpgradeTarget,
+  deps: GcpUpgradeDeps,
+): Promise<GcpUpgradeOutcome> {
+  const failed: GcpUpgradeOutcome = { ok: false, rolledBack: false };
   const { reporter: r, run } = deps;
   const { projectId } = target;
 
@@ -102,7 +154,7 @@ export async function upgradeGcpInstall(
   if (!images.ok) {
     sPre.failed("Couldn't resolve the release images");
     r.error(images.error);
-    return false;
+    return failed;
   }
   const planned = await planAppRoll(
     {
@@ -119,34 +171,46 @@ export async function upgradeGcpInstall(
   if (!planned.ok) {
     sPre.failed("Pre-flight failed");
     r.error(planned.error);
-    return false;
+    return failed;
   }
-  const plan = planned.plan;
+  const plan = withPriorRevisions(planned.plan, deps, r);
   sPre.done(`Pre-flight ok — ${plan.services.length} services planned`);
   reportPlan(plan, r);
 
   // 2. P21 ship 4 — signatures against the Caelo release workflow's
   // identity: refuses a compromised registry, a typosquat or a fork's image.
   if (!target.skipVerify) {
-    if (!(await deps.verifyImages(plan.services))) return false;
+    if (!(await deps.verifyImages(plan.services))) return failed;
   } else {
     r.warn("--skip-verify set — image signatures NOT verified.");
   }
 
   // 3. The first change: a failure leaves the install exactly as it was.
-  const sBak = r.step("Taking a pre-upgrade Cloud SQL backup...");
-  const backup = await takeSqlBackup(
-    run,
-    { projectId, env: target.env },
-    `pre-upgrade to ${target.targetTag}`,
-    deps.now,
-  );
-  if (!backup.ok) {
-    sBak.failed(`Pre-upgrade backup failed: ${backup.error}`);
-    r.warn(backupFailureHelp({ projectId }));
-    return false;
+  //    A resumed run keeps the interrupted run's backup: a new one could
+  //    already hold the half-migrated schema.
+  let backup: { readonly ok: true; readonly backup: SqlBackup };
+  if (deps.resume?.backup) {
+    backup = { ok: true, backup: deps.resume.backup };
+    r.info(
+      `Continuing an interrupted update: keeping its pre-upgrade backup ${backup.backup.backupId}.`,
+    );
+  } else {
+    const sBak = r.step("Taking a pre-upgrade Cloud SQL backup...");
+    const taken = await takeSqlBackup(
+      run,
+      { projectId, env: target.env },
+      `pre-upgrade to ${target.targetTag}`,
+      deps.now,
+    );
+    if (!taken.ok) {
+      sBak.failed(`Pre-upgrade backup failed: ${taken.error}`);
+      r.warn(backupFailureHelp({ projectId }));
+      return failed;
+    }
+    sBak.done(`Pre-upgrade backup ${taken.backup.backupId} of ${taken.backup.instance} taken`);
+    backup = taken;
+    deps.onCheckpoint?.({ backup: taken.backup });
   }
-  sBak.done(`Pre-upgrade backup ${backup.backup.backupId} of ${backup.backup.instance} taken`);
 
   // 4. Converge, the part before the roll. The upgrader job runs the ops
   //    image with rights over the whole app, so it is deployed only when its
@@ -160,7 +224,7 @@ export async function upgradeGcpInstall(
     ...(deps.http ? { http: deps.http } : {}),
     ...(deps.provisionerIdentity ? { provisionerIdentity: deps.provisionerIdentity } : {}),
   });
-  if (!(await converge.beforeAppRoll())) return false;
+  if (!(await converge.beforeAppRoll())) return failed;
 
   // 5. App-roll, with the converge steps that sit between its own.
   let health: HealthProbe | null = null;
@@ -169,7 +233,7 @@ export async function upgradeGcpInstall(
     if (!probe.ok) {
       r.error(probe.error);
       r.warn("No migrations ran and no traffic moved.");
-      return false;
+      return failed;
     }
     health = probe.probe;
   }
@@ -178,8 +242,8 @@ export async function upgradeGcpInstall(
       plan,
       backup: backup.backup,
       targetVersion: /^\d+\.\d+\.\d+/.test(target.targetTag) ? target.targetTag : null,
-      // Unknown until the signed release manifest names it (epic #696).
-      migrationsContract: null,
+      // Unknown on the terminal path until the signed release manifest names it.
+      migrationsContract: target.migrationsContract ?? null,
     },
     converge.hooks,
     {
@@ -191,7 +255,7 @@ export async function upgradeGcpInstall(
       recordDigests: deps.recordDigests,
     },
   );
-  if (!rolled.ok) return false;
+  if (!rolled.ok) return { ok: false, rolledBack: rolled.rolledBack };
   r.success(`Upgrade to ${target.targetTag} complete (admin + gateway revisions serving).`);
   r.info(
     `Pre-upgrade backup: ${backup.backup.backupId} (restore: ${restoreCommand(backup.backup)})`,
@@ -212,7 +276,39 @@ export async function upgradeGcpInstall(
       "Some converge steps did not succeed (see above); the install is not marked as converged, so in-product updates stay unavailable until a re-run of upgrade completes them.",
     );
   }
-  return true;
+  return { ok: true };
+}
+
+/**
+ * The plan with the rollback targets an interrupted run recorded (#819): it
+ * may have rolled a service already, so the revision serving NOW would be
+ * the new release's. A fresh run records the planned ones instead.
+ */
+function withPriorRevisions(
+  plan: AppRollPlan,
+  deps: GcpUpgradeDeps,
+  r: UpgradeReporter,
+): AppRollPlan {
+  const recorded = deps.resume?.priorRevisions;
+  if (!recorded) {
+    const prior = Object.fromEntries(plan.services.map((s) => [s.slug, s.priorRevision])) as Record<
+      RollSlug,
+      string
+    >;
+    deps.onCheckpoint?.({ priorRevisions: prior });
+    return plan;
+  }
+  return {
+    ...plan,
+    services: plan.services.map((s) => {
+      const before = recorded[s.slug];
+      if (before === s.priorRevision) return s;
+      r.info(
+        `Continuing an interrupted update: ${s.slug} goes back to ${before} (what served before it started) if the new release fails its checks.`,
+      );
+      return { ...s, priorRevision: before };
+    }),
+  };
 }
 
 /**

package/src/upgrader-assess.test.ts

@@ -54,7 +54,11 @@ const verified = (m: Partial<ReleaseManifest> = {}): ReleaseManifestResult => ({
 });
 const broken = (
   code: "registry" | "signature" | "schema" | "blob-digest" | "version-mismatch" | "artifact-shape",
-): ReleaseManifestResult => ({ ok: false, error: { code, message: `${code} problem` } });
+  transient?: true,
+): ReleaseManifestResult => ({
+  ok: false,
+  error: { code, message: `${code} problem`, ...(transient ? { transient } : {}) },
+});
 
 interface Row {
   readonly name: string;
@@ -73,9 +77,16 @@ const ROWS: readonly Row[] = [
   { name: "a signed, newer, app-only release", expect: "proceed" },
   {
     name: "registry unreachable",
-    manifest: broken("registry"),
+    manifest: broken("registry", true),
     expect: "failed/registry",
-    reasonContains: "Nothing was changed",
+    reasonContains: "try again later",
+  },
+  {
+    // Regression #865: a 404 never heals, so it must not end retryable.
+    name: "no signed manifest for the target (404)",
+    manifest: broken("registry"),
+    expect: "refused/manifest-missing",
+    reasonContains: "has no signed release manifest",
   },
   { name: "bad signature", manifest: broken("signature"), expect: "refused/signature" },
   { name: "tampered blob", manifest: broken("blob-digest"), expect: "refused/signature" },
@@ -95,6 +106,7 @@ const ROWS: readonly Row[] = [
     name: "same version",
     installed: { version: "0.11.0", infraContractVersion: 2 },
     expect: "refused/not-newer",
+    reasonContains: "v0.11.0 already serves on this install",
   },
   {
     name: "downgrade",
@@ -327,3 +339,80 @@ describe("assessUpgradeRequest — self-hosted (the host agent, #696 Phase 4c)",
     ).toBe("refused/contract-migrations");
   });
 });
+
+describe("assessUpgradeRequest — the converge route (#819)", () => {
+  const assess = (row: {
+    manifest?: ReleaseManifestResult;
+    installed?: InstalledState;
+    trigger?: "manual" | "auto";
+    policy?: Partial<StoredUpdatePolicy>;
+  }) =>
+    assessUpgradeRequest({
+      request: { targetVersion: "0.11.0", trigger: row.trigger ?? "manual" },
+      manifest: row.manifest ?? verified({ infraContractVersion: 3 }),
+      installed: row.installed ?? INSTALLED,
+      policy: { ...POLICY, ...row.policy },
+      now: NOW,
+      route: "converge",
+    });
+  const code = (d: ReturnType<typeof assess>) =>
+    d.kind === "stop" ? `${d.status}/${d.codes.join(",")}` : d.kind;
+
+  it("installs a release that raises the infrastructure contract: that is its job", () => {
+    expect(code(assess({}))).toBe("proceed");
+  });
+
+  it("the contract bump is no reason to warn about destructive migrations", () => {
+    const d = assess({});
+    expect(d.kind === "proceed" ? d.warnings : ["stopped"]).toEqual([]);
+  });
+
+  it("converges automatically only with the Owner's autoConverge (#864), default off", () => {
+    expect(code(assess({ trigger: "auto" }))).toBe("refused/policy");
+    const off = assess({ trigger: "auto" });
+    expect(off.kind === "stop" ? off.reason : "").toContain("Settings → Updates");
+    expect(code(assess({ trigger: "auto", policy: { autoConverge: true } }))).toBe("proceed");
+  });
+
+  it("autoConverge never widens the rest of the policy: kinds, mode and pause still decide", () => {
+    const on = { autoConverge: true };
+    // 0.10.45 → 0.11.0 is a minor release.
+    expect(code(assess({ trigger: "auto", policy: { ...on, autoMinor: false } }))).toBe(
+      "refused/policy",
+    );
+    expect(code(assess({ trigger: "auto", policy: { ...on, mode: "notify" } }))).toBe(
+      "refused/policy",
+    );
+    expect(code(assess({ trigger: "auto", policy: { ...on, paused: true } }))).toBe(
+      "refused/policy",
+    );
+    // The Owner's click needs no autoConverge.
+    expect(code(assess({ trigger: "manual" }))).toBe("proceed");
+  });
+
+  it("keeps every other refusal: signature, downgrade, minFromVersion, unknown version", () => {
+    expect(code(assess({ manifest: broken("signature") }))).toBe("refused/signature");
+    expect(code(assess({ manifest: broken("blob-digest") }))).toBe("refused/signature");
+    expect(code(assess({ installed: { version: "0.11.0", infraContractVersion: 2 } }))).toBe(
+      "refused/not-newer",
+    );
+    expect(
+      code(assess({ manifest: verified({ infraContractVersion: 3, minFromVersion: "0.10.50" }) })),
+    ).toBe("refused/min-from-version");
+    expect(code(assess({ installed: { version: null, infraContractVersion: 2 } }))).toBe(
+      "needs_cloud_shell/install-version-unknown",
+    );
+  });
+
+  it("the upgrader's own route still hands the contract bump on, naming the converge job first", () => {
+    const d = assessUpgradeRequest({
+      request: { targetVersion: "0.11.0", trigger: "manual" },
+      manifest: verified({ infraContractVersion: 3 }),
+      installed: INSTALLED,
+      policy: POLICY,
+      now: NOW,
+    });
+    expect(code(d)).toBe("needs_cloud_shell/infra-contract");
+    expect(d.kind === "stop" ? d.reason : "").toContain("converge job");
+  });
+});