@caelo-cms/provisioning 0.10.44 → 0.10.47

package/dist/upgrade/app-roll.js

@@ -0,0 +1,270 @@
+// SPDX-License-Identifier: MPL-2.0
+import { gatewayServiceAccountEmail, runServiceAccountEmail } from "../gcp-names.js";
+import { adminMediaVolume } from "../stack-contract.js";
+import { liveContainerEnv, liveContainerMemory, liveVolumes, planAdminMemory, planContractEnv, planMediaVolume, rollService, serviceRollArgs, } from "../stack-converge.js";
+import { restoreCommand } from "./backup.js";
+import { describeServiceJson, findCurrentRevision, findServiceUrl, pinTraffic, resolveGcpResourceName, } from "./gcp-lookup.js";
+/** The roll order: the gateway follows the admin, never the other way round. */
+export const ROLL_ORDER = ["admin", "gateway"];
+/**
+ * Read both services and plan their rolls: prior revisions (the rollback
+ * targets), env-contract changes, the admin's memory and media volume. Makes
+ * no change; fails when anything a roll needs is missing.
+ */
+export async function planAppRoll(install, images, run) {
+    const services = [];
+    for (const slug of ROLL_ORDER) {
+        const prefix = `caelo-${install.env}-${slug}`;
+        const serviceName = await resolveGcpResourceName(run, "run-service", prefix, install.projectId, install.region);
+        if (!serviceName)
+            return { ok: false, error: `Could not find the ${prefix}* Cloud Run service` };
+        const priorRevision = await findCurrentRevision(run, install.projectId, install.region, serviceName);
+        if (!priorRevision) {
+            return {
+                ok: false,
+                error: `Could not capture the current ${slug} revision — refusing to roll`,
+            };
+        }
+        const json = await describeServiceJson(run, install.projectId, install.region, serviceName);
+        if (!json) {
+            return {
+                ok: false,
+                error: `Could not read the ${slug} service's configuration — refusing to roll`,
+            };
+        }
+        services.push({
+            slug,
+            serviceName,
+            ...images[slug],
+            priorRevision,
+            liveEnv: liveContainerEnv(json),
+            liveMemory: liveContainerMemory(json),
+            liveVolumes: liveVolumes(json),
+        });
+    }
+    const env = planEnv(install, services, []);
+    if (!env.ok)
+        return { ok: false, error: `the install's env contract can't be applied: ${env.error}` };
+    // Without the media volume every upload is lost on the next revision or
+    // scale-to-zero, so a volume the roll cannot add fails the plan.
+    const admin = services.find((s) => s.slug === "admin");
+    const media = planMediaVolume(admin.liveVolumes, adminMediaVolume(install.projectId, install.env));
+    if (!media.ok)
+        return { ok: false, error: `the admin's media volume can't be set up: ${media.error}` };
+    const warnings = [];
+    const rolls = services.map((s) => {
+        // #553 — the admin runs the Lighthouse quality audit; raise it to the
+        // stack's memory default (never lowered; an unparsable value is kept).
+        const memory = s.slug === "admin" ? planAdminMemory(s.liveMemory) : null;
+        if (memory && !memory.ok)
+            warnings.push(`admin memory left as is: ${memory.error}`);
+        return {
+            ...s,
+            envFlags: env.services[s.slug].flags,
+            envChanges: env.services[s.slug].changes,
+            resourceFlags: memory?.ok ? memory.flags : [],
+            volumeFlags: s.slug === "admin" ? media.flags : [],
+            volumeChanges: s.slug === "admin" ? media.changes : [],
+        };
+    });
+    return { ok: true, plan: { install, services: rolls, warnings } };
+}
+function planEnv(install, services, leaveUntouched) {
+    const deployed = Object.fromEntries(services.map((s) => [s.slug, { serviceName: s.serviceName, liveEnv: s.liveEnv }]));
+    return planContractEnv({
+        provider: install.provider,
+        projectId: install.projectId,
+        env: install.env,
+        domain: install.domain,
+        region: install.region,
+        stagingHost: install.stagingHost,
+    }, deployed, { leaveUntouched });
+}
+/**
+ * The plan with `names` left exactly as the services have them — for env
+ * vars that point at something a converge step could not set up.
+ */
+export function leavingEnvUntouched(plan, names) {
+    if (names.length === 0)
+        return plan;
+    const env = planEnv(plan.install, plan.services, names);
+    if (!env.ok)
+        return plan;
+    return {
+        ...plan,
+        services: plan.services.map((s) => ({
+            ...s,
+            envFlags: env.services[s.slug].flags,
+            envChanges: env.services[s.slug].changes,
+        })),
+    };
+}
+/** Print what the plan will change, one line per change. */
+export function reportPlan(plan, reporter) {
+    for (const w of plan.warnings)
+        reporter.warn(w);
+    for (const s of plan.services) {
+        for (const c of s.volumeChanges)
+            reporter.info(`${s.slug} media: ${c}`);
+        for (const f of s.resourceFlags) {
+            reporter.info(`${s.slug} resources: ${s.liveMemory ?? "(default)"} → ${f}`);
+        }
+        for (const c of s.envChanges) {
+            reporter.info(`${s.slug} env ${c.name}: ${c.from === undefined ? "(unset)" : c.from} → ${c.to === undefined ? "(removed)" : c.to}`);
+        }
+    }
+}
+/** Run the app-roll. See the file comment for the sequence. */
+export async function executeAppRoll(input, hooks, deps) {
+    const { reporter: r, run } = deps;
+    const { install } = input.plan;
+    let plan = input.plan;
+    const fail = (phase, migrated) => ({
+        ok: false,
+        phase,
+        migrated,
+    });
+    // A probe that cannot reach the install now would only fail after the
+    // migrations, and roll a healthy release back.
+    if (deps.health) {
+        const s = r.step("Checking the health check can reach admin + gateway...");
+        const base = await deps.health.baseline().catch((e) => ({
+            ok: false,
+            error: e instanceof Error ? e.message : String(e),
+        }));
+        if (!base.ok) {
+            s.failed(`Health check can't reach the install: ${base.error}`);
+            r.warn("No migrations ran and no traffic moved. Fix the access problem, or re-run with --skip-health-check to roll with Cloud Run's readiness check only.");
+            return fail("health-baseline", false);
+        }
+        s.done(`Health check reaches the install (${base.detail})`);
+    }
+    else {
+        r.warn("--skip-health-check set — the new revisions get Cloud Run's readiness check only.");
+    }
+    // Migrations BEFORE any traffic moves, with the NEW admin image: the old
+    // image does not carry the release's migration files (v0.9.2).
+    const admin = plan.services.find((s) => s.slug === "admin");
+    const sMig = r.step("Applying DB migrations (idempotent)...");
+    const mig = await deps.migrate(admin.imageRef);
+    if (!mig.ok) {
+        sMig.failed(`Migrations failed (${mig.error ?? "unknown"}). Aborting upgrade.`);
+        r.warn(`No traffic was shifted. Inspect the Cloud Run Job logs:\n  gcloud logging read 'resource.type=cloud_run_job AND resource.labels.job_name=~"caelo-migrate-.*"' --project=${install.projectId} --limit=50\n${restoreHint(input, "if a migration left the schema half-applied")}`);
+        return fail("migrations", true);
+    }
+    sMig.done("Migrations applied");
+    if (hooks.afterMigrations) {
+        const converged = await hooks.afterMigrations();
+        if (!converged.ok)
+            return fail("converge", true);
+        plan = leavingEnvUntouched(plan, converged.leaveUntouched);
+    }
+    const rolled = [];
+    const rollBack = async (alsoCurrent) => {
+        const services = alsoCurrent ? [...rolled, alsoCurrent] : rolled;
+        if (services.length === 0)
+            return;
+        r.warn(`Rolling back ${services.length} service(s) to the revisions that served before...`);
+        for (const p of [...services].reverse()) {
+            const ok = await pinTraffic(run, install.projectId, install.region, p.serviceName, p.priorRevision);
+            if (ok)
+                r.info(`  ${p.slug} traffic restored to ${p.priorRevision}`);
+            else
+                r.error(`  ${p.slug} rollback FAILED — pin ${p.priorRevision} by hand`);
+            await hooks.afterRollback?.(p.slug);
+        }
+    };
+    for (const p of plan.services) {
+        const s = r.step(`Rolling ${p.slug} → ${p.digest.slice(0, 19)}...`);
+        const before = (await hooks.beforeRoll?.(p.slug)) ?? { ok: true };
+        if (!before.ok) {
+            s.failed(before.error);
+            await rollBack();
+            return fail("roll", true);
+        }
+        const upd = await rollService(serviceRollArgs({
+            serviceName: p.serviceName,
+            region: install.region,
+            projectId: install.projectId,
+            imageRef: p.imageRef,
+            serviceAccount: p.slug === "admin"
+                ? runServiceAccountEmail(install.projectId, install.env)
+                : gatewayServiceAccountEmail(install.projectId, install.env),
+            envFlags: p.envFlags,
+            resourceFlags: p.resourceFlags,
+            volumeFlags: p.volumeFlags,
+        }), { run, ...(deps.sleep ? { sleep: deps.sleep } : {}) });
+        if (!upd.ok) {
+            s.failed(`Failed: ${upd.stderr.trim()}`);
+            // The failed update created no serving revision; only undo what the
+            // hook changed for it, then the services that rolled before.
+            await hooks.afterRollback?.(p.slug);
+            await rollBack();
+            return fail("roll", true);
+        }
+        // `update --image` only moves traffic when the service has no explicit
+        // traffic config — but a rollback pins traffic to the prior revision,
+        // and that pin survives later updates. Moving traffic to latest on
+        // every roll is idempotent and un-pins services an earlier failed
+        // upgrade left pinned.
+        const flip = await run([
+            "run",
+            "services",
+            "update-traffic",
+            p.serviceName,
+            "--region",
+            install.region,
+            "--project",
+            install.projectId,
+            "--to-latest",
+            "--quiet",
+        ]);
+        if (!flip.ok) {
+            s.failed(`Traffic flip to latest failed: ${flip.stderr.trim()}`);
+            await rollBack(p);
+            return fail("roll", true);
+        }
+        if (!(await findServiceUrl(run, install.projectId, install.region, p.serviceName))) {
+            s.failed(`Could not resolve the service URL for ${p.slug} — rolling back`);
+            await rollBack(p);
+            return fail("roll", true);
+        }
+        s.done(`${p.slug} rolled to ${p.digest.slice(0, 19)}...`);
+        rolled.push(p);
+    }
+    if (deps.health) {
+        const s = r.step("Deep health check (database, migrations, version)...");
+        // A probe that throws is a failed check: roll back, never leave the
+        // new revisions serving unverified.
+        const deep = await deps.health.deep({ version: input.targetVersion }).catch((e) => ({
+            ok: false,
+            error: e instanceof Error ? e.message : String(e),
+        }));
+        if (!deep.ok) {
+            s.failed(`Deep health check failed: ${deep.error}`);
+            await rollBack();
+            r.warn(restoreHint(input, "if the previous release now fails against the migrated schema"));
+            return fail("health", true);
+        }
+        s.done(`Healthy: ${deep.detail}`);
+    }
+    const digests = {
+        admin: plan.services.find((s) => s.slug === "admin").digest,
+        gateway: plan.services.find((s) => s.slug === "gateway").digest,
+    };
+    await deps.recordDigests(digests);
+    return { ok: true, digests };
+}
+/**
+ * The restore hint after migrations ran and the roll failed. Expand-only
+ * migrations leave a schema the previous release still runs on, so restoring
+ * is only advised outright for contract-type migrations.
+ */
+function restoreHint(input, when) {
+    const cmd = restoreCommand(input.backup);
+    if (input.migrationsContract === true) {
+        return `This release's migrations are contract-type: the previous release may not work against the migrated schema. Restore the pre-upgrade backup ${input.backup.backupId} (overwrites all data written since):\n  ${cmd}`;
+    }
+    return `Pre-upgrade backup: ${input.backup.backupId}. Restore it only ${when} (overwrites all data written since):\n  ${cmd}`;
+}
+//# sourceMappingURL=app-roll.js.map

package/dist/upgrade/app-roll.js.map

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

package/dist/upgrade/backup.d.ts

@@ -0,0 +1,48 @@
+/**
+ * On-demand Cloud SQL backups (epic #696): the `backup` lifecycle command and
+ * the backup every upgrade takes before its migrations. Both GCP providers
+ * (`gcp`, `gcp-firebase`) keep their data in the same `caelo-<env>-pg*` Cloud
+ * SQL instance, so one implementation serves both.
+ *
+ * The backup id is what makes the pre-upgrade backup useful: it lands in the
+ * upgrade's output and in the restore hint printed when the upgrade has to
+ * roll back after migrations ran.
+ */
+import type { GcloudRunner } from "../gcloud-retry.js";
+/** A finished on-demand backup. */
+export interface SqlBackup {
+    readonly projectId: string;
+    /** Cloud SQL instance name (Pulumi-suffixed). */
+    readonly instance: string;
+    /** Cloud SQL backup run id. */
+    readonly backupId: string;
+}
+export type SqlBackupResult = {
+    readonly ok: true;
+    readonly backup: SqlBackup;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Take an on-demand backup of the install's Cloud SQL instance and return its
+ * id. `gcloud sql backups create` waits for the backup to finish but does not
+ * print the id in a stable shape, so the backup carries a unique description
+ * and is looked up by it afterwards.
+ *
+ * @param purpose short reason recorded in the backup's description, e.g. "pre-upgrade to 0.11.0"
+ */
+export declare function takeSqlBackup(run: GcloudRunner, install: {
+    readonly projectId: string;
+    readonly env: string;
+}, purpose: string, now?: () => Date): Promise<SqlBackupResult>;
+/** The command that restores `backup` over its instance (overwrites the current data). */
+export declare function restoreCommand(backup: SqlBackup): string;
+/**
+ * What to tell the operator when a pre-upgrade backup failed: why nothing
+ * happened, and how to get past it.
+ */
+export declare function backupFailureHelp(install: {
+    readonly projectId: string;
+}): string;
+//# sourceMappingURL=backup.d.ts.map

package/dist/upgrade/backup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/upgrade/backup.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD,mCAAmC;AACnC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAC7D,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,IAAuB,GACjC,OAAO,CAAC,eAAe,CAAC,CA8C1B;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAExD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAQjF"}

package/dist/upgrade/backup.js

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: MPL-2.0
+import { gcpNamePrefix } from "../gcp-names.js";
+import { resolveGcpResourceName } from "./gcp-lookup.js";
+/**
+ * Take an on-demand backup of the install's Cloud SQL instance and return its
+ * id. `gcloud sql backups create` waits for the backup to finish but does not
+ * print the id in a stable shape, so the backup carries a unique description
+ * and is looked up by it afterwards.
+ *
+ * @param purpose short reason recorded in the backup's description, e.g. "pre-upgrade to 0.11.0"
+ */
+export async function takeSqlBackup(run, install, purpose, now = () => new Date()) {
+    const instance = await resolveGcpResourceName(run, "sql-instance", `${gcpNamePrefix(install.env)}-pg`, install.projectId);
+    if (!instance) {
+        return {
+            ok: false,
+            error: `no ${gcpNamePrefix(install.env)}-pg* Cloud SQL instance in project ${install.projectId} (or listing it was denied)`,
+        };
+    }
+    const description = `caelo-cms ${purpose} ${now().toISOString()}`;
+    const project = ["--project", install.projectId];
+    const create = await run([
+        "sql",
+        "backups",
+        "create",
+        "--instance",
+        instance,
+        ...project,
+        "--description",
+        description,
+    ]);
+    if (!create.ok) {
+        return { ok: false, error: `backup of ${instance} failed: ${create.stderr.trim()}` };
+    }
+    const list = await run([
+        "sql",
+        "backups",
+        "list",
+        "--instance",
+        instance,
+        ...project,
+        `--filter=description="${description}"`,
+        "--format=value(id)",
+    ]);
+    const backupId = list.ok ? list.stdout.trim().split("\n")[0]?.trim() : "";
+    if (!backupId) {
+        return {
+            ok: false,
+            error: `backup of ${instance} was created but its id could not be read (${list.ok ? "no backup carries the description" : list.stderr.trim()}); find it with: gcloud sql backups list --instance=${instance} --project=${install.projectId}`,
+        };
+    }
+    return { ok: true, backup: { projectId: install.projectId, instance, backupId } };
+}
+/** The command that restores `backup` over its instance (overwrites the current data). */
+export function restoreCommand(backup) {
+    return `gcloud sql backups restore ${backup.backupId} --restore-instance=${backup.instance} --project=${backup.projectId}`;
+}
+/**
+ * What to tell the operator when a pre-upgrade backup failed: why nothing
+ * happened, and how to get past it.
+ */
+export function backupFailureHelp(install) {
+    return [
+        "Nothing was changed: no migrations ran and no traffic moved.",
+        "Fix the cause and re-run upgrade. Common causes:",
+        `  - the account lacks Cloud SQL backup rights (roles/cloudsql.editor or owner on ${install.projectId})`,
+        "  - another backup or maintenance operation is running on the instance (wait, then retry)",
+        `  - the instance is stopped: gcloud sql instances describe <instance> --project=${install.projectId}`,
+    ].join("\n");
+}
+//# sourceMappingURL=backup.js.map

package/dist/upgrade/backup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.js","sourceRoot":"","sources":["../../src/upgrade/backup.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAcnC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAezD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAiB,EACjB,OAA6D,EAC7D,OAAe,EACf,MAAkB,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;IAElC,MAAM,QAAQ,GAAG,MAAM,sBAAsB,CAC3C,GAAG,EACH,cAAc,EACd,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAClC,OAAO,CAAC,SAAS,CAClB,CAAC;IACF,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,MAAM,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,sCAAsC,OAAO,CAAC,SAAS,6BAA6B;SAC5H,CAAC;IACJ,CAAC;IACD,MAAM,WAAW,GAAG,aAAa,OAAO,IAAI,GAAG,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;IAClE,MAAM,OAAO,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC;QACvB,KAAK;QACL,SAAS;QACT,QAAQ;QACR,YAAY;QACZ,QAAQ;QACR,GAAG,OAAO;QACV,eAAe;QACf,WAAW;KACZ,CAAC,CAAC;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,QAAQ,YAAY,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC;IACvF,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC;QACrB,KAAK;QACL,SAAS;QACT,MAAM;QACN,YAAY;QACZ,QAAQ;QACR,GAAG,OAAO;QACV,yBAAyB,WAAW,GAAG;QACvC,oBAAoB;KACrB,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1E,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,aAAa,QAAQ,8CAA8C,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,mCAAmC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,uDAAuD,QAAQ,cAAc,OAAO,CAAC,SAAS,EAAE;SAC7O,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,CAAC;AACpF,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,cAAc,CAAC,MAAiB;IAC9C,OAAO,8BAA8B,MAAM,CAAC,QAAQ,uBAAuB,MAAM,CAAC,QAAQ,cAAc,MAAM,CAAC,SAAS,EAAE,CAAC;AAC7H,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAuC;IACvE,OAAO;QACL,8DAA8D;QAC9D,kDAAkD;QAClD,oFAAoF,OAAO,CAAC,SAAS,GAAG;QACxG,2FAA2F;QAC3F,mFAAmF,OAAO,CAAC,SAAS,EAAE;KACvG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/upgrade/converge.d.ts

@@ -0,0 +1,45 @@
+import type { GcloudRunner, Sleep } from "../gcloud-retry.js";
+import type { InstallMetadata } from "../install-state.js";
+import { type HttpFetch } from "../runtime-secrets.js";
+import type { AppRollHooks, AppRollPlan } from "./app-roll.js";
+import type { UpgradeReporter } from "./reporter.js";
+/**
+ * Whether the install must converge before an app-roll to a release that
+ * expects infrastructure contract `targetVersion` (infra-contract.ts). An
+ * install with no recorded version has never completed a converge under
+ * this scheme and always needs one.
+ */
+export declare function needsConverge(install: Pick<InstallMetadata, "infraContractVersion">, targetVersion: number): boolean;
+export interface ConvergeDeps {
+    readonly run: GcloudRunner;
+    readonly sleep?: Sleep;
+    /** Cloud SQL Admin API calls (database role passwords). */
+    readonly http?: HttpFetch;
+    readonly reporter: UpgradeReporter;
+    /**
+     * The operator's own identity step, run first: the CLI moves the
+     * provisioner SA to keyless impersonation (provisioner-identity.ts), which
+     * needs the operator's gcloud account and local install dir. False aborts.
+     */
+    readonly provisionerIdentity?: () => Promise<boolean>;
+}
+export interface ConvergeSession {
+    /**
+     * Before the app-roll: runtime identities + secrets, stack invariants, MCP
+     * access. False when a step the install cannot work without failed —
+     * nothing app-side changed then.
+     */
+    beforeAppRoll(): Promise<boolean>;
+    /** The steps the app-roll runs between its own. */
+    readonly hooks: AppRollHooks;
+    /** After a successful app-roll: retire bindings nothing reads any more. */
+    afterAppRoll(): Promise<void>;
+    /**
+     * Whether every converge step succeeded — only then may the install's
+     * infrastructure contract version be recorded.
+     */
+    complete(): boolean;
+}
+/** Start a converge for the install `plan` rolls. */
+export declare function startConverge(plan: AppRollPlan, ownerEmail: string, deps: ConvergeDeps): ConvergeSession;
+//# sourceMappingURL=converge.d.ts.map

package/dist/upgrade/converge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"converge.d.ts","sourceRoot":"","sources":["../../src/upgrade/converge.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG3D,OAAO,EAGL,KAAK,SAAS,EAGf,MAAM,uBAAuB,CAAC;AAQ/B,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAsB,MAAM,eAAe,CAAC;AACnF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,sBAAsB,CAAC,EACtD,aAAa,EAAE,MAAM,GACpB,OAAO,CAET;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,2EAA2E;IAC3E,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B;;;OAGG;IACH,QAAQ,IAAI,OAAO,CAAC;CACrB;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,YAAY,GACjB,eAAe,CAmQjB"}