@caelo-cms/provisioning 0.10.55 → 0.10.58

package/dist/upgrader-iam-preflight.d.ts

@@ -0,0 +1,123 @@
+import type { HttpFetch } from "./runtime-secrets.js";
+/** A resource IAM can be asked about. */
+export type IamResource = {
+    readonly kind: "project";
+    readonly projectId: string;
+} | {
+    readonly kind: "service-account";
+    readonly projectId: string;
+    readonly email: string;
+} | {
+    readonly kind: "run-job";
+    readonly projectId: string;
+    readonly region: string;
+    readonly name: string;
+} | {
+    readonly kind: "bucket";
+    readonly bucket: string;
+}
+/** Objects under `prefix/` in `bucket`, behind a name-conditioned grant (probed). */
+ | {
+    readonly kind: "bucket-objects";
+    readonly bucket: string;
+    readonly prefix: string;
+} | {
+    readonly kind: "artifact-repository";
+    readonly projectId: string;
+    readonly location: string;
+    readonly repository: string;
+};
+/** One thing the run will do, the permissions it takes, and where. */
+export interface AccessCheck {
+    /** What the upgrader could not do without them, in plain words. */
+    readonly need: string;
+    readonly resource: IamResource;
+    readonly permissions: readonly string[];
+}
+/** A check with the permissions it lacks. */
+export interface MissingAccess {
+    readonly check: AccessCheck;
+    readonly missing: readonly string[];
+    /**
+     * Permissions that could not be judged because another one is missing
+     * first (storage.objects.get needs storage.objects.list to be testable).
+     */
+    readonly unchecked?: readonly string[];
+}
+/** The permissions IAM confirmed on one resource, or why it could not be asked. */
+export type GrantedResult = {
+    readonly ok: true;
+    readonly granted: readonly string[];
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** Asks IAM which of `permissions` the job's identity holds on `resource`. */
+export interface IamTester {
+    granted(resource: IamResource, permissions: readonly string[]): Promise<GrantedResult>;
+}
+/** How the self-check came out. */
+export type PreflightOutcome = {
+    readonly kind: "ok";
+} | {
+    readonly kind: "missing";
+    readonly missing: readonly MissingAccess[];
+}
+/** IAM could not be asked about at least one resource; nothing was judged missing. */
+ | {
+    readonly kind: "error";
+    readonly errors: readonly string[];
+};
+/** The object the `install/` probes name. It is never written: every probe fails its precondition. */
+export declare const PREFLIGHT_PROBE_OBJECT = ".caelo-iam-preflight";
+/**
+ * Every permission an upgrader run needs after its decision, grouped by
+ * what it is for (upgrade/app-roll.ts, migration-runner.ts, backup.ts,
+ * health.ts, state-store.ts, the self-update in upgrader-job.ts). Keep in
+ * step with the grants in upgrader-setup.ts: a permission listed here that
+ * setup does not grant stops every update.
+ */
+export declare function upgraderAccessChecks(target: {
+    readonly projectId: string;
+    readonly region: string;
+    readonly env: string;
+}): AccessCheck[];
+/** Ask IAM about every check (one call per resource); never throws. */
+export declare function runIamPreflight(checks: readonly AccessCheck[], tester: IamTester): Promise<PreflightOutcome>;
+/**
+ * The request's end reason for missing permissions: every one of them, each
+ * with what it is for, then the one next step.
+ */
+export declare function preflightMissingReason(missing: readonly MissingAccess[]): string;
+/** The request's end reason when IAM could not be asked. */
+export declare function preflightErrorReason(errors: readonly string[]): string;
+/** A resource's full name, as IAM and the messages name it. */
+export declare function resourceName(r: IamResource): string;
+/**
+ * The real {@link IamTester}: Google's REST APIs with the job's own access
+ * token. `token` is asked once per call (gcloud caches it).
+ *
+ * @example
+ * const tester = restIamTester({ http: fetch, token: async () => "<access token>" });
+ * await tester.granted({ kind: "project", projectId: "acme" }, ["run.services.get"]);
+ */
+export declare function restIamTester(deps: {
+    readonly http: HttpFetch;
+    readonly token: () => Promise<string>;
+}): IamTester;
+/** The testIamPermissions request for a resource that has one. */
+export declare function testIamCall(resource: Exclude<IamResource, {
+    kind: "bucket-objects";
+}>, permissions: readonly string[]): {
+    url: string;
+    method: "GET" | "POST";
+    body?: string;
+};
+/** The precondition-guarded request that tests one object permission (see the file comment). */
+export declare function objectProbeCall(resource: Extract<IamResource, {
+    kind: "bucket-objects";
+}>, permission: string): {
+    url: string;
+    method: "GET" | "POST" | "DELETE";
+} | null;
+//# sourceMappingURL=upgrader-iam-preflight.d.ts.map

package/dist/upgrader-iam-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrader-iam-preflight.d.ts","sourceRoot":"","sources":["../src/upgrader-iam-preflight.ts"],"names":[],"mappings":"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"}

package/dist/upgrader-iam-preflight.js

@@ -0,0 +1,414 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * The upgrader job's IAM self-check (#818): before it takes the state lock
+ * or changes anything, the job asks Google Cloud whether its own service
+ * account holds every permission the run will need, and stops with ALL the
+ * missing ones named when it does not.
+ *
+ * Why: the first live in-app update died at its first bucket write (#799)
+ * because a grant that looked right could never match the call. Unit tests
+ * against a fake gcloud cannot catch that class of bug; asking IAM can, and
+ * asking first means a missing grant ends the run before the backup, the
+ * migrations or the roll, with a reason a non-technical Owner can pass on
+ * ("Run the upgrade once with Cloud Shell" re-converges the grants).
+ *
+ * How each permission is checked, without doing the action:
+ *
+ *   - `testIamPermissions` on the resource the call acts on — the project,
+ *     a service account, the upgrader's own job, the ops bucket, the release
+ *     image repository. Google returns the subset the CALLER holds; no
+ *     permission is needed to ask.
+ *   - The `install/` objects in the ops bucket are the exception. The
+ *     upgrader's object rights there are an IAM grant CONDITIONED on the
+ *     object name (upgrader-setup.ts `installStateCondition`), and a bucket's
+ *     testIamPermissions evaluates conditions against the bucket's own
+ *     resource name, never an object's — it would report a grant that works
+ *     as missing (the mirror image of #799). Cloud Storage has no object
+ *     testIamPermissions on uniform-access buckets, so those three are
+ *     probed with requests that can never change anything: a read of an
+ *     object that does not exist, and an upload + a delete preconditioned
+ *     on generation 1, which no object ever has. Cloud Storage authorizes a
+ *     request before it evaluates its preconditions, so 403 means the
+ *     permission is missing and 404/412 means it is held — with one
+ *     exception: a read of an absent object is answered 403 whenever the
+ *     caller lacks storage.objects.list, so objects.get is probed only once
+ *     the bucket check confirmed list, and reported "unchecked" otherwise.
+ *
+ * Direct VPC egress (#818): the migration job and both services are
+ * deployed with `--network/--subnet`. Google documents the compute
+ * permissions for that (`compute.subnetworks.use`, …) on the Cloud Run
+ * SERVICE AGENT (roles/run.serviceAgent has them), not on the principal
+ * that deploys, so they are not checked here and the upgrader gets no
+ * compute role (UPGRADER_FORBIDDEN_ROLES). The real-GCP upgrader smoke test
+ * (.github/workflows/upgrader-smoke.yml) is where that shows on real GCP:
+ * each stable release, installed on the smoke install through Settings →
+ * Updates, must serve cleanly before the next tag ships.
+ *
+ * Everything here is pure except {@link restIamTester}, which takes its
+ * HTTP client and token source as arguments.
+ */
+import { z } from "zod";
+import { auditServiceAccountEmail, gatewayServiceAccountEmail, mcpIapServiceAccountEmail, runServiceAccountEmail, upgraderJobName, upgraderServiceAccountEmail, } from "./gcp-names.js";
+import { OPS_INSTALL_PREFIX, opsBucketName } from "./state-backend.js";
+import { RELEASE_REGISTRY } from "./upgrade/release-images.js";
+/** The object the `install/` probes name. It is never written: every probe fails its precondition. */
+export const PREFLIGHT_PROBE_OBJECT = ".caelo-iam-preflight";
+/**
+ * Every permission an upgrader run needs after its decision, grouped by
+ * what it is for (upgrade/app-roll.ts, migration-runner.ts, backup.ts,
+ * health.ts, state-store.ts, the self-update in upgrader-job.ts). Keep in
+ * step with the grants in upgrader-setup.ts: a permission listed here that
+ * setup does not grant stops every update.
+ */
+export function upgraderAccessChecks(target) {
+    const { projectId, region, env } = target;
+    const project = { kind: "project", projectId };
+    const sa = (email) => ({ kind: "service-account", projectId, email });
+    const bucket = opsBucketName(projectId);
+    return [
+        {
+            need: "read which release the site's admin and gateway serve",
+            resource: project,
+            permissions: [
+                "run.services.get",
+                "run.services.list",
+                "run.revisions.get",
+                "run.revisions.list",
+            ],
+        },
+        {
+            need: "deploy the new release to the admin and gateway and move their traffic",
+            resource: project,
+            permissions: ["run.services.update", "run.operations.get"],
+        },
+        {
+            need: "run the database migrations as a one-off job (and check whether an earlier run still holds the install's lock)",
+            resource: project,
+            permissions: [
+                "run.jobs.create",
+                "run.jobs.delete",
+                "run.jobs.get",
+                "run.jobs.run",
+                "run.executions.get",
+            ],
+        },
+        {
+            need: "back up the database before anything changes",
+            resource: project,
+            permissions: [
+                "cloudsql.backupRuns.create",
+                "cloudsql.backupRuns.get",
+                "cloudsql.backupRuns.list",
+                "cloudsql.instances.get",
+                "cloudsql.instances.list",
+            ],
+        },
+        {
+            need: "run the admin and the migration job as the admin's service account",
+            resource: sa(runServiceAccountEmail(projectId, env)),
+            permissions: ["iam.serviceAccounts.actAs"],
+        },
+        {
+            need: "run the gateway as its service account",
+            resource: sa(gatewayServiceAccountEmail(projectId, env)),
+            permissions: ["iam.serviceAccounts.actAs"],
+        },
+        {
+            // #875 — every app-roll moves the audit job onto the new admin image
+            // (upgrade/audit-job-roll.ts), and upgrader-setup.ts grants actAs on
+            // the job's account for exactly that.
+            need: "move the quality-audit job onto the new admin image",
+            resource: project,
+            permissions: ["run.jobs.update"],
+        },
+        {
+            need: "run the quality-audit job as its service account after moving it",
+            resource: sa(auditServiceAccountEmail(projectId, env)),
+            permissions: ["iam.serviceAccounts.actAs"],
+        },
+        {
+            need: "keep the upgrader job running as its own service account after it updates itself",
+            resource: sa(upgraderServiceAccountEmail(projectId, env)),
+            permissions: ["iam.serviceAccounts.actAs"],
+        },
+        {
+            need: "sign in to the admin (through its identity proxy) for the health check",
+            resource: sa(mcpIapServiceAccountEmail(projectId)),
+            permissions: ["iam.serviceAccounts.signJwt"],
+        },
+        {
+            need: "move the upgrader itself onto the new release",
+            resource: { kind: "run-job", projectId, region, name: upgraderJobName(env) },
+            permissions: ["run.jobs.get", "run.jobs.update"],
+        },
+        {
+            need: "list the install's ops bucket (every write there lists it first)",
+            resource: { kind: "bucket", bucket },
+            permissions: ["storage.objects.list"],
+        },
+        {
+            need: `read and write the install's records and its state lock (${OPS_INSTALL_PREFIX}/ in the ops bucket)`,
+            resource: { kind: "bucket-objects", bucket, prefix: OPS_INSTALL_PREFIX },
+            permissions: ["storage.objects.get", "storage.objects.create", "storage.objects.delete"],
+        },
+        {
+            need: "read Caelo's release images",
+            resource: {
+                kind: "artifact-repository",
+                projectId: RELEASE_REGISTRY.project,
+                location: RELEASE_REGISTRY.region,
+                repository: RELEASE_REGISTRY.repo,
+            },
+            permissions: ["artifactregistry.repositories.downloadArtifacts"],
+        },
+    ];
+}
+/** Ask IAM about every check (one call per resource); never throws. */
+export async function runIamPreflight(checks, tester) {
+    // One question per resource: the project alone carries four checks.
+    const byResource = new Map();
+    for (const c of checks) {
+        const key = resourceName(c.resource);
+        const entry = byResource.get(key) ?? { resource: c.resource, permissions: new Set() };
+        for (const p of c.permissions)
+            entry.permissions.add(p);
+        byResource.set(key, entry);
+    }
+    const granted = new Map();
+    /** Permissions that could not be judged (see the object probes below). */
+    const unverified = new Map();
+    const errors = [];
+    const ask = async (key, resource, permissions) => {
+        let r;
+        try {
+            r = await tester.granted(resource, [...permissions].sort());
+        }
+        catch (e) {
+            r = { ok: false, error: e instanceof Error ? e.message : String(e) };
+        }
+        if (r.ok)
+            granted.set(key, new Set(r.granted));
+        else
+            errors.push(`${key}: ${r.error}`);
+    };
+    const entries = [...byResource];
+    await Promise.all(entries
+        .filter(([, e]) => e.resource.kind !== "bucket-objects")
+        .map(([key, e]) => ask(key, e.resource, [...e.permissions])));
+    // The object probes go second: Cloud Storage answers a read of an absent
+    // object with 403 — not 404 — when the caller lacks storage.objects.list
+    // on the bucket, so the objects.get probe means something only once list
+    // is confirmed. Without it, get is reported as unchecked, never missing.
+    await Promise.all(entries
+        .filter(([, e]) => e.resource.kind === "bucket-objects")
+        .map(([key, e]) => {
+        const r = e.resource;
+        const listHeld = granted.get(resourceName({ kind: "bucket", bucket: r.bucket }))?.has(OBJECT_LIST) ??
+            false;
+        const asked = [...e.permissions].filter((p) => listHeld || p !== OBJECT_GET);
+        if (asked.length < e.permissions.size)
+            unverified.set(key, new Set([OBJECT_GET]));
+        return ask(key, e.resource, asked);
+    }));
+    if (errors.length > 0)
+        return { kind: "error", errors: errors.sort() };
+    const missing = [];
+    for (const check of checks) {
+        const key = resourceName(check.resource);
+        const held = granted.get(key) ?? new Set();
+        const unknown = unverified.get(key) ?? new Set();
+        const lacking = check.permissions.filter((p) => !held.has(p) && !unknown.has(p));
+        const unchecked = check.permissions.filter((p) => unknown.has(p));
+        if (lacking.length > 0 || unchecked.length > 0) {
+            missing.push({ check, missing: lacking, ...(unchecked.length > 0 ? { unchecked } : {}) });
+        }
+    }
+    return missing.length === 0 ? { kind: "ok" } : { kind: "missing", missing };
+}
+const OBJECT_LIST = "storage.objects.list";
+const OBJECT_GET = "storage.objects.get";
+/**
+ * The request's end reason for missing permissions: every one of them, each
+ * with what it is for, then the one next step.
+ */
+export function preflightMissingReason(missing) {
+    const lines = missing.map((m) => {
+        const where = resourceName(m.check.resource);
+        const parts = [
+            ...(m.missing.length > 0 ? [`missing ${m.missing.join(", ")} on ${where}`] : []),
+            ...(m.unchecked && m.unchecked.length > 0
+                ? [
+                    `${m.unchecked.join(", ")} on ${where} could not be checked: without storage.objects.list Cloud Storage answers 403 for any absent object, held or not`,
+                ]
+                : []),
+        ];
+        return `it ${m.missing.length > 0 ? "cannot" : "may not be able to"} ${m.check.need} (${parts.join("; ")})`;
+    });
+    return `Nothing was changed: the upgrader checked its access before starting and is missing permissions this update needs — ${lines.join("; ")}. Run the upgrade once with Cloud Shell; it repairs the upgrader's access.`;
+}
+/** The request's end reason when IAM could not be asked. */
+export function preflightErrorReason(errors) {
+    return `Nothing was changed: the upgrader could not check its access before starting (${errors.join("; ")}). Try again in a few minutes; if it keeps failing, run the upgrade once with Cloud Shell.`;
+}
+/** A resource's full name, as IAM and the messages name it. */
+export function resourceName(r) {
+    switch (r.kind) {
+        case "project":
+            return `projects/${r.projectId}`;
+        case "service-account":
+            return `projects/${r.projectId}/serviceAccounts/${r.email}`;
+        case "run-job":
+            return `projects/${r.projectId}/locations/${r.region}/jobs/${r.name}`;
+        case "bucket":
+            return `gs://${r.bucket}`;
+        case "bucket-objects":
+            return `gs://${r.bucket}/${r.prefix}/`;
+        case "artifact-repository":
+            return `projects/${r.projectId}/locations/${r.location}/repositories/${r.repository}`;
+    }
+}
+const testIamResponse = z.object({ permissions: z.array(z.string()).optional() });
+/**
+ * The real {@link IamTester}: Google's REST APIs with the job's own access
+ * token. `token` is asked once per call (gcloud caches it).
+ *
+ * @example
+ * const tester = restIamTester({ http: fetch, token: async () => "<access token>" });
+ * await tester.granted({ kind: "project", projectId: "acme" }, ["run.services.get"]);
+ */
+export function restIamTester(deps) {
+    return {
+        async granted(resource, permissions) {
+            const bearer = await deps.token();
+            if (!bearer)
+                return { ok: false, error: "no access token for the upgrader's account" };
+            const auth = { Authorization: `Bearer ${bearer}` };
+            if (resource.kind === "bucket-objects") {
+                return probeObjects(deps.http, auth, resource, permissions);
+            }
+            const call = testIamCall(resource, permissions);
+            const res = await deps.http(call.url, {
+                method: call.method,
+                headers: { ...auth, ...(call.body ? { "Content-Type": "application/json" } : {}) },
+                ...(call.body ? { body: call.body } : {}),
+            });
+            const text = await res.text();
+            if (!res.ok)
+                return { ok: false, error: `HTTP ${res.status} ${text.trim().slice(0, 300)}` };
+            let raw;
+            try {
+                raw = JSON.parse(text);
+            }
+            catch {
+                return { ok: false, error: "testIamPermissions answered without JSON" };
+            }
+            const parsed = testIamResponse.safeParse(raw);
+            if (!parsed.success) {
+                return { ok: false, error: "testIamPermissions answered without a permission list" };
+            }
+            // An empty answer omits `permissions`: none of them is held.
+            return { ok: true, granted: parsed.data.permissions ?? [] };
+        },
+    };
+}
+/** The testIamPermissions request for a resource that has one. */
+export function testIamCall(resource, permissions) {
+    const body = JSON.stringify({ permissions });
+    switch (resource.kind) {
+        case "project":
+            return {
+                url: `https://cloudresourcemanager.googleapis.com/v1/projects/${encodeURIComponent(resource.projectId)}:testIamPermissions`,
+                method: "POST",
+                body,
+            };
+        case "service-account":
+            return {
+                url: `https://iam.googleapis.com/v1/projects/${encodeURIComponent(resource.projectId)}/serviceAccounts/${encodeURIComponent(resource.email)}:testIamPermissions`,
+                method: "POST",
+                body,
+            };
+        case "run-job":
+            return {
+                url: `https://run.googleapis.com/v2/projects/${encodeURIComponent(resource.projectId)}/locations/${encodeURIComponent(resource.region)}/jobs/${encodeURIComponent(resource.name)}:testIamPermissions`,
+                method: "POST",
+                body,
+            };
+        case "bucket": {
+            const q = permissions.map((p) => `permissions=${encodeURIComponent(p)}`).join("&");
+            return {
+                url: `https://storage.googleapis.com/storage/v1/b/${encodeURIComponent(resource.bucket)}/iam/testPermissions?${q}`,
+                method: "GET",
+            };
+        }
+        case "artifact-repository":
+            return {
+                url: `https://artifactregistry.googleapis.com/v1/projects/${encodeURIComponent(resource.projectId)}/locations/${encodeURIComponent(resource.location)}/repositories/${encodeURIComponent(resource.repository)}:testIamPermissions`,
+                method: "POST",
+                body,
+            };
+    }
+}
+const OBJECT_PROBES = {
+    // A read of an object that does not exist: 404 once authorized.
+    "storage.objects.get": { method: "GET", held: [404, 200] },
+    // An upload that must match generation 1: never true, so 412 once authorized.
+    "storage.objects.create": { method: "POST", held: [412] },
+    // A delete that must match generation 1: 404 (absent) or 412 once authorized.
+    "storage.objects.delete": { method: "DELETE", held: [404, 412] },
+};
+/** The precondition-guarded request that tests one object permission (see the file comment). */
+export function objectProbeCall(resource, permission) {
+    const probe = OBJECT_PROBES[permission];
+    if (!probe)
+        return null;
+    const bucket = encodeURIComponent(resource.bucket);
+    const object = encodeURIComponent(`${resource.prefix}/${PREFLIGHT_PROBE_OBJECT}`);
+    switch (probe.method) {
+        case "GET":
+            return {
+                url: `https://storage.googleapis.com/storage/v1/b/${bucket}/o/${object}`,
+                method: "GET",
+            };
+        case "POST":
+            return {
+                url: `https://storage.googleapis.com/upload/storage/v1/b/${bucket}/o?uploadType=media&name=${object}&ifGenerationMatch=1`,
+                method: "POST",
+            };
+        case "DELETE":
+            return {
+                url: `https://storage.googleapis.com/storage/v1/b/${bucket}/o/${object}?ifGenerationMatch=1`,
+                method: "DELETE",
+            };
+    }
+}
+async function probeObjects(http, auth, resource, permissions) {
+    const granted = [];
+    for (const permission of permissions) {
+        const call = objectProbeCall(resource, permission);
+        const probe = OBJECT_PROBES[permission];
+        if (!call || !probe) {
+            return { ok: false, error: `no probe for ${permission} on ${resourceName(resource)}` };
+        }
+        const res = await http(call.url, {
+            method: call.method,
+            headers: call.method === "POST" ? { ...auth, "Content-Type": "application/octet-stream" } : auth,
+            ...(call.method === "POST" ? { body: "" } : {}),
+        });
+        const text = await res.text();
+        if (probe.held.includes(res.status)) {
+            // 200 on the upload would mean an object was written; held[] for
+            // create has no 200, so that lands below as an error, loudly.
+            granted.push(permission);
+        }
+        else if (res.status === 403) {
+        }
+        else {
+            return {
+                ok: false,
+                error: `probing ${permission} on ${resourceName(resource)}: HTTP ${res.status} ${text.trim().slice(0, 300)}`,
+            };
+        }
+    }
+    return { ok: true, granted };
+}
+//# sourceMappingURL=upgrader-iam-preflight.js.map

package/dist/upgrader-iam-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrader-iam-preflight.js","sourceRoot":"","sources":["../src/upgrader-iam-preflight.ts"],"names":[],"mappings":"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"}

package/dist/upgrader-job.d.ts

@@ -10,18 +10,34 @@
  * but cannot change IAM, service accounts or secrets. One run:
  *
  *   1. claim the oldest pending request (ending a run that died mid-way);
- *   2. read what the install runs from install.json in its ops bucket;
+ *   2. read what the install runs from install.json in its ops bucket; when
+ *      it names other images than the ones serving, judge against the
+ *      serving release if a signed release manifest names both its images,
+ *      else stop (upgrader-records.ts, #860);
  *   3. fetch the release manifest from the FIXED registry and verify its
  *      signature (release-manifest.ts) — no registry, identity or digest
  *      ever comes from the request, the env or argv;
  *   4. decide (upgrader-assess.ts): refuse a bad signature, a downgrade, a
  *      release below its minFromVersion, an automatic run the policy does
- *      not allow; hand an infrastructure change to Cloud Shell;
+ *      not allow; hand an infrastructure change back (the admin routes
+ *      it to the converge job, #819; Cloud Shell on installs without one);
+ *   -- ask IAM whether the job's account holds every permission the rest
+ *      of the run needs (upgrader-iam-preflight.ts, #818); any missing one
+ *      ends the run as needs-Cloud-Shell, all of them named, nothing changed;
+ *   -- only now take the install's state lock (#815), confirm install.json
+ *      is unchanged since step 2, and write step 2's correction. Everything
+ *      above only reads, so no lock problem can hide the verdict; a stop
+ *      verdict still corrects the records when the lock is free. Only a
+ *      verdict judged on drift asks for the lock even when it stops: the
+ *      serving images were read without it, and a run that holds it may be
+ *      half-way through its own roll — then the answer is "another install
+ *      operation is running", never a drift or Cloud Shell verdict;
  *   5. take a Cloud SQL backup — no backup, no change;
  *   6. app-roll (upgrade/app-roll.ts) with no converge hooks: migrations
  *      with the new admin image, admin then gateway, deep health check,
  *      traffic back onto the previous revisions on any failure;
- *   7. record the new digests + version in install.json;
+ *   7. record the new digests + version in install.json (a failed write
+ *      ends the run as failed, never as succeeded);
  *   8. move this job onto the release's own ops image, last.
  *
  * Every step is narrated into `platform_update_events` (upgrader-reporter.ts).
@@ -35,6 +51,7 @@ import type { InstallMetadata } from "./install-state.js";
 import type { ReleaseManifestResult } from "./release-manifest.js";
 import { type AppRollPlan } from "./upgrade/app-roll.js";
 import type { HealthProbe } from "./upgrade/health.js";
+import { type IamTester } from "./upgrader-iam-preflight.js";
 import { type JobLog } from "./upgrader-reporter.js";
 /** A request the job claimed, with the policy as it stood at claim time. */
 export interface ClaimedUpdate {
@@ -88,15 +105,22 @@ export interface UpgraderJobDeps {
     readonly env: string;
     /** This Cloud Run execution, for the log link; null outside Cloud Run. */
     readonly execution: string | null;
+    /**
+     * Asks IAM which permissions the job's own account holds (#818), for the
+     * self-check right after the decision. Never the action itself.
+     */
+    readonly iam: IamTester;
     /** fetchVerifiedReleaseManifest against the fixed registry. */
     readonly fetchManifest: (version: string) => Promise<ReleaseManifestResult>;
     /**
-     * Take the install's state lock (the one `pulumi up` and `state migrate`
-     * hold) for the whole run; returns its release. Throws when another run
-     * holds it.
+     * Take the install's state lock (the one `pulumi up`, `state migrate` and
+     * the CLI `upgrade` hold) right before the run's first write; returns its
+     * release. Breaks a lock whose holder has ended and reports that through
+     * `onBreak` (state-store.ts). Throws StateLockHeldError when a live run
+     * holds it, any other error when it cannot be taken or judged.
      */
-    readonly lockState: () => () => void;
-    /** install.json from the install's ops bucket (null when absent). */
+    readonly lockState: (onBreak: (message: string) => void) => () => void;
+    /** install.json as the ops bucket holds it NOW (null when absent) — never cached. */
     readonly readInstall: () => InstallMetadata | null;
     readonly writeInstall: (meta: InstallMetadata) => void;
     /** Runs both migration targets with the NEW admin image. */
@@ -129,5 +153,5 @@ export declare function runUpgraderJob(deps: UpgraderJobDeps): Promise<UpgraderR
  *
  * @returns whether the end was written (false after the last attempt failed)
  */
-export declare function recordUpdateEnd(queue: UpdateQueue, requestId: string, end: UpdateEnd, log: JobLog, sleep?: Sleep): Promise<boolean>;
+export declare function recordUpdateEnd(queue: Pick<UpdateQueue, "finish">, requestId: string, end: UpdateEnd, log: JobLog, sleep?: Sleep): Promise<boolean>;
 //# sourceMappingURL=upgrader-job.d.ts.map