@caelo-cms/provisioning 0.10.29 → 0.10.31

package/dist/stack-contract.js

@@ -0,0 +1,455 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * What a GCP install looks like, declared once for both ways of producing
+ * one: the Pulumi stacks (`stacks/gcp`, `stacks/gcp-firebase`) for new
+ * installs and `pulumi up`, and `cms-provision upgrade` (stack-converge.ts)
+ * for existing installs, which rolls images through gcloud without running
+ * Pulumi.
+ *
+ * Before this contract, everything added to the stacks after an install was
+ * created never reached that install: `CAELO_SITE_URL` (so `site_base_url`
+ * stayed unset and Stage failed), the run SA's `run.viewer` on the gateway
+ * (Firebase Hosting deploys 403'd), the telemetry roles, the one-year CDN
+ * TTLs. Three parts close that gap:
+ *
+ *   - {@link adminEnvContract} / {@link gatewayEnvContract}: the complete
+ *     env of the two Cloud Run services — plain values and Secret Manager
+ *     references. The stacks deploy them as the Cloud Run `envs`; upgrade
+ *     applies them (`--update-env-vars` / `--update-secrets`) in the same
+ *     `services update` that rolls the image.
+ *   - {@link stackIamInvariants} + {@link STATIC_CDN_POLICY}: the IAM
+ *     bindings and CDN settings upgrade ensures with gcloud.
+ *   - {@link STACK_IAM_NOT_ENSURED}: bindings upgrade deliberately leaves to
+ *     Pulumi, each with the reason. The parity test
+ *     (stack-contract-parity.test.ts) fails when a stack declares an IAM
+ *     binding that is in neither list, so a new binding cannot ship without
+ *     a decision about existing installs.
+ *
+ * No secret value is ever a plain env var: database URLs carry no password
+ * (the apps add it from the `<NAME>_PASSWORD` var, @caelo-cms/shared
+ * `databaseUrlFromEnv`), and every secret is a `secretKeyRef` to Secret
+ * Manager. Anyone with `run.services.get` sees secret names, never values.
+ *
+ * Pure module — the stacks import it from `dist/`.
+ */
+import { gatewayServiceAccountEmail, gcpBucketName, gcpNamePrefix, gcpSecretId, mcpIapServiceAccountEmail, operatorAccessJobResource, runServiceAccountEmail, staticPublisherServiceAccountId, } from "./gcp-names.js";
+/** Port Cloud SQL Postgres listens on (private IP). */
+const DATABASE_PORT = 5432;
+/**
+ * Password-less connection URLs for a Cloud SQL instance at `host`. The
+ * password reaches the apps separately, as a Secret Manager reference
+ * ({@link SERVICE_SECRET_ENV}).
+ */
+export function databaseUrls(host) {
+    const url = (role, db) => `postgresql://${role}@${host}:${DATABASE_PORT}/${db}?sslmode=require`;
+    return {
+        admin: url("admin_role", "cms_admin"),
+        publicAdmin: url("admin_role", "cms_public"),
+        public: url("public_role", "cms_public"),
+    };
+}
+/** The public site's base URL, as the admin seeds `site_base_url` from it (#551). */
+export function publicSiteUrl(domain) {
+    return `https://${domain}`;
+}
+/**
+ * The admin env var naming the MCP service account (issue #37). `upgrade`
+ * leaves it untouched when it could not set that account up.
+ */
+export const MCP_ENV_VAR = "CAELO_MCP_IAP_SERVICE_ACCOUNT";
+/**
+ * The admin env var naming the operator-access sync job. `upgrade` leaves it
+ * untouched when it could not set the job up.
+ */
+export const OPERATOR_ACCESS_JOB_ENV_VAR = "CAELO_OPERATOR_ACCESS_JOB";
+/** Where the admin image ships the static-generator CLI. */
+const GENERATOR_CLI = "/app/apps/static-generator/src/cli.ts";
+/**
+ * Secrets the CLI generates and stores (runtime-secrets.ts
+ * `ensureGeneratedSecrets`) rather than Pulumi: the wizard creates them
+ * before `pulumi up`, upgrade creates them on installs that predate them.
+ * Pulumi only references them, so a `pulumi up` after an upgrade never
+ * collides with a secret upgrade created.
+ */
+export const CLI_GENERATED_SECRETS = [
+    "internal-secret",
+    "tool-approval-secret",
+];
+/**
+ * Each service's Secret Manager-backed env vars and the secret each reads.
+ * The services' run SAs get `secretAccessor` on exactly these secrets
+ * ({@link runtimeSecretBindings}), so this table is also the least-privilege
+ * boundary between the two services.
+ */
+export const SERVICE_SECRET_ENV = {
+    admin: {
+        ADMIN_DATABASE_PASSWORD: "postgres-password",
+        PUBLIC_ADMIN_DATABASE_PASSWORD: "postgres-password",
+        // P18 — encrypts AI provider keys and other at-rest secrets in cms_admin.
+        CAELO_SECRET_KEK: "secret-kek",
+        // P15.1 — HMAC key of the /api/internal/* bearer tokens (internal-jwt.ts).
+        CAELO_INTERNAL_SECRET: "internal-secret",
+        // Binds an AI tool-approval to the exact call the operator approved
+        // (admin-core ai/providers/_sdk-shared.ts).
+        CAELO_TOOL_APPROVAL_SECRET: "tool-approval-secret",
+    },
+    gateway: {
+        // Known gap against CLAUDE.md §2 ("never let the API Gateway hold
+        // admin_role credentials"): the gateway reads site_settings, rate
+        // limits, captcha challenges, the request log and the plugin registry
+        // through an admin_role pool (apps/api-gateway/src/server.ts), and fails
+        // to boot without it. Until that moves behind a narrower role the
+        // gateway needs this credential; it is no longer a plain env var.
+        ADMIN_DATABASE_PASSWORD: "postgres-password",
+        PUBLIC_DATABASE_PASSWORD: "postgres-password",
+    },
+};
+/** The secrets `service` reads (deduplicated, table order). */
+export function serviceSecrets(service) {
+    return [...new Set(Object.values(SERVICE_SECRET_ENV[service]))];
+}
+/**
+ * Env vars an older stack set that the contract no longer gives a service;
+ * upgrade removes them. The gateway never used the KEK, and its run SA
+ * cannot read it.
+ */
+export const RETIRED_SERVICE_ENV = {
+    admin: [],
+    gateway: ["CAELO_SECRET_KEK"],
+};
+function secretEnv(service, env) {
+    return Object.entries(SERVICE_SECRET_ENV[service]).map(([name, secret]) => ({
+        name,
+        valueSource: { secretKeyRef: { secret: gcpSecretId(env, secret), version: "latest" } },
+    }));
+}
+// ===========================================================================
+// Env contracts
+// ===========================================================================
+/** Env vars both services carry. */
+function commonEnv(inputs) {
+    return [
+        { name: "CAELO_PROVIDER", value: inputs.provider },
+        { name: "CAELO_ENV", value: inputs.env },
+        {
+            name: "MEDIA_STORAGE_URL",
+            value: `gs://${gcpBucketName(inputs.projectId, inputs.env, "media")}`,
+        },
+    ];
+}
+/**
+ * The env of the gateway service. Order is stable so the stacks see no
+ * spurious diffs.
+ */
+export function gatewayEnvContract(inputs) {
+    return [
+        ...commonEnv(inputs),
+        { name: "PUBLIC_DATABASE_URL", value: inputs.databaseUrls.public },
+        // See the known gap noted on SERVICE_SECRET_ENV.gateway.
+        { name: "ADMIN_DATABASE_URL", value: inputs.databaseUrls.admin },
+        ...secretEnv("gateway", inputs.env),
+    ];
+}
+/**
+ * The env of the admin service.
+ *
+ * @example
+ *   adminEnvContract({ provider: "gcp", projectId: "p", env: "production",
+ *     domain: "example.com", region: "europe-west1",
+ *     databaseUrls: databaseUrls("10.20.0.3") })
+ *   // → [{ name: "CAELO_PROVIDER", value: "gcp" }, …,
+ *   //    { name: "CAELO_SITE_URL", value: "https://example.com" }, …,
+ *   //    { name: "CAELO_SECRET_KEK", valueSource: { secretKeyRef: … } }, …]
+ */
+export function adminEnvContract(inputs) {
+    const { projectId, env, domain } = inputs;
+    const admin = [
+        ...commonEnv(inputs),
+        { name: "ADMIN_DATABASE_URL", value: inputs.databaseUrls.admin },
+        // admin_role on cms_public: cross-DB reads, plugin DDL, migrations.
+        // Not public_role (write-limited).
+        { name: "PUBLIC_ADMIN_DATABASE_URL", value: inputs.databaseUrls.publicAdmin },
+        // #551 — the admin seeds site_defaults.site_base_url from it (canonical,
+        // og:url, sitemap) when it is not configured yet.
+        { name: "CAELO_SITE_URL", value: publicSiteUrl(domain) },
+        { name: "CAELO_GENERATOR_CLI", value: GENERATOR_CLI },
+        // Issue #37 — shown in the /security/mcp `claude mcp add` command.
+        { name: MCP_ENV_VAR, value: mcpIapServiceAccountEmail(projectId) },
+        // The operator-access sync job the admin starts after user/role changes
+        // (admin-core security/operator-access/gcp-job-trigger.ts).
+        {
+            name: OPERATOR_ACCESS_JOB_ENV_VAR,
+            value: operatorAccessJobResource(projectId, inputs.region, env),
+        },
+    ];
+    if (inputs.provider === "gcp") {
+        // v0.2.78 — the GCS StaticPublisher: Stage uploads to staging,
+        // Confirm-publish copies to static.
+        admin.push({ name: "CAELO_STATIC_BUCKET", value: gcpBucketName(projectId, env, "static") }, { name: "CAELO_STAGING_BUCKET", value: gcpBucketName(projectId, env, "staging") });
+    }
+    else {
+        // v0.3.1 — the Firebase publisher deploys to this site and declares
+        // the /api/** rewrite to the gateway service.
+        admin.push({ name: "CAELO_FIREBASE_SITE", value: inputs.firebaseSiteId }, { name: "CAELO_GATEWAY_SERVICE", value: inputs.gatewayService }, { name: "CAELO_GATEWAY_REGION", value: inputs.region });
+    }
+    admin.push(...secretEnv("admin", env));
+    return admin;
+}
+// ===========================================================================
+// IAM + CDN invariants
+// ===========================================================================
+/**
+ * Cloud CDN policy of the `gcp` stack's static backend bucket. The GCS
+ * publisher sets an explicit Cache-Control on every object: content-hashed
+ * assets `max-age=31536000, immutable`, pages `max-age=60` + SWR. In
+ * CACHE_ALL_STATIC mode `clientTtl` clamps the max-age browsers see and
+ * `maxTtl` caps the edge TTL, so both must allow a year or the immutable
+ * policy is cut back to 1h (#555). `defaultTtl` applies only to responses
+ * without a max-age.
+ */
+export const STATIC_CDN_POLICY = {
+    cacheMode: "CACHE_ALL_STATIC",
+    defaultTtl: 3600,
+    maxTtl: 31536000,
+    clientTtl: 31536000,
+};
+const SECRET_ACCESSOR = "roles/secretmanager.secretAccessor";
+/**
+ * The `secretAccessor` bindings both stacks declare: each service's run SA
+ * on exactly the secrets its env reads ({@link SERVICE_SECRET_ENV}).
+ */
+export function runtimeSecretBindings() {
+    return ["admin", "gateway"].flatMap((service) => serviceSecrets(service).map((secret) => ({
+        service,
+        secret,
+        // The admin's keep the names they had when one SA served both.
+        stackResource: service === "admin" ? `${secret}-binding` : `gateway-${secret}-binding`,
+    })));
+}
+function secretAccessors() {
+    return runtimeSecretBindings().map((b) => ({
+        stackResource: b.stackResource,
+        role: SECRET_ACCESSOR,
+        member: b.service === "admin" ? "run-sa" : "gateway-sa",
+        target: { kind: "secret", name: b.secret },
+        onFailure: "abort",
+        why: `the ${b.service} reads ${b.secret} from Secret Manager at boot`,
+    }));
+}
+/** v0.6.6 — a custom runtime SA gets no telemetry roles implicitly. */
+const TELEMETRY = [
+    {
+        stackResource: "run-log-writer",
+        role: "roles/logging.logWriter",
+        member: "run-sa",
+        target: { kind: "project" },
+        onFailure: "warn",
+        why: "container logs reach Cloud Logging",
+    },
+    {
+        stackResource: "run-metric-writer",
+        role: "roles/monitoring.metricWriter",
+        member: "run-sa",
+        target: { kind: "project" },
+        onFailure: "warn",
+        why: "CPU/memory metrics reach Cloud Monitoring (autoscaling signals)",
+    },
+    {
+        stackResource: "gateway-log-writer",
+        role: "roles/logging.logWriter",
+        member: "gateway-sa",
+        target: { kind: "project" },
+        onFailure: "warn",
+        why: "gateway container logs reach Cloud Logging",
+    },
+    {
+        stackResource: "gateway-metric-writer",
+        role: "roles/monitoring.metricWriter",
+        member: "gateway-sa",
+        target: { kind: "project" },
+        onFailure: "warn",
+        why: "gateway CPU/memory metrics reach Cloud Monitoring (autoscaling signals)",
+    },
+];
+const GCP_ONLY = [
+    {
+        stackResource: "static-public-read",
+        role: "roles/storage.objectViewer",
+        member: "allUsers",
+        target: { kind: "bucket", bucket: "static" },
+        onFailure: "abort",
+        why: "Cloud CDN fetches the public site from the static bucket",
+    },
+    {
+        stackResource: "media-rw",
+        role: "roles/storage.objectAdmin",
+        member: "run-sa",
+        target: { kind: "bucket", bucket: "media" },
+        onFailure: "abort",
+        why: "the admin stores and serves media",
+    },
+    {
+        stackResource: "admin-static-rw",
+        role: "roles/storage.objectAdmin",
+        member: "run-sa",
+        target: { kind: "bucket", bucket: "static" },
+        onFailure: "abort",
+        why: "Confirm-publish copies the staged build into the static bucket",
+    },
+    {
+        stackResource: "admin-staging-rw",
+        role: "roles/storage.objectAdmin",
+        member: "run-sa",
+        target: { kind: "bucket", bucket: "staging" },
+        onFailure: "abort",
+        why: "Stage uploads builds to the private staging bucket (v0.2.78)",
+    },
+    {
+        stackResource: "static-publisher-rw",
+        role: "roles/storage.objectAdmin",
+        member: "static-publisher-sa",
+        target: { kind: "bucket", bucket: "static" },
+        onFailure: "warn",
+        why: "manual `deploy` uploads as the static-publisher SA (the admin publishes without it)",
+    },
+    {
+        stackResource: "iap-invoke-admin",
+        role: "roles/run.invoker",
+        member: "iap-service-agent",
+        target: { kind: "run-service", service: "admin" },
+        onFailure: "abort",
+        why: "IAP forwards admin traffic to Cloud Run as its service agent",
+    },
+];
+const GCP_FIREBASE_ONLY = [
+    {
+        stackResource: "media-rw",
+        role: "roles/storage.objectAdmin",
+        member: "run-sa",
+        target: { kind: "bucket", bucket: "media" },
+        onFailure: "abort",
+        why: "the admin stores and serves media",
+    },
+    {
+        stackResource: "run-firebase-hosting",
+        role: "roles/firebasehosting.admin",
+        member: "run-sa",
+        target: { kind: "project" },
+        onFailure: "abort",
+        why: "the admin publishes the site to Firebase Hosting",
+    },
+    {
+        stackResource: "gateway-public-invoker",
+        role: "roles/run.invoker",
+        member: "allUsers",
+        target: { kind: "run-service", service: "gateway" },
+        onFailure: "abort",
+        why: "Firebase Hosting rewrites /api/** to the public gateway",
+    },
+    {
+        stackResource: "gateway-viewer-for-admin-sa",
+        role: "roles/run.viewer",
+        member: "run-sa",
+        target: { kind: "run-service", service: "gateway" },
+        onFailure: "abort",
+        why: "Firebase Hosting checks run.services.get on the rewrite target at deploy time (v0.6.5; without it every publish 403s)",
+    },
+    {
+        stackResource: "admin-iap-sa-invoker",
+        role: "roles/run.invoker",
+        member: "iap-service-agent",
+        target: { kind: "run-service", service: "admin" },
+        onFailure: "abort",
+        why: "IAP forwards admin traffic to Cloud Run as its service agent",
+    },
+];
+/** Every IAM binding upgrade ensures on an install of `provider`. */
+export function stackIamInvariants(provider) {
+    return [
+        ...secretAccessors(),
+        ...(provider === "gcp" ? GCP_ONLY : GCP_FIREBASE_ONLY),
+        ...TELEMETRY,
+    ];
+}
+/**
+ * IAM bindings the stacks declare that upgrade deliberately does not ensure,
+ * keyed by provider and the stack resource's logical name as written in the
+ * stack source, with each `${…}` placeholder written as `*`.
+ */
+export const STACK_IAM_NOT_ENSURED = {
+    gcp: {
+        "admin-iap-allow-*": "The IAP allowlist is operator-managed membership from stack config; upgrade must not re-add principals an Owner removed.",
+        "mcp-token-creator-*": "Ensured by ensureMcpIapAccess (mcp-iap.ts).",
+        "admin-iap-mcp": "Ensured by ensureMcpIapAccess (mcp-iap.ts).",
+        "edge-log-sink-bq-perms": "The member is the sink's generated writer identity, which only Pulumi knows; analytics only.",
+    },
+    "gcp-firebase": {
+        "admin-iap-*": "The IAP allowlist is operator-managed membership from stack config; upgrade must not re-add principals an Owner removed.",
+        "admin-invoker-*": "Per-principal invoker for the IAP allowlist (operator-managed, see admin-iap-*).",
+        "mcp-token-creator-*": "Ensured by ensureMcpIapAccess (mcp-iap.ts).",
+        "admin-iap-mcp": "Ensured by ensureMcpIapAccess (mcp-iap.ts).",
+    },
+};
+/** The IAM member string for a principal on a concrete install. */
+export function iamMember(principal, install) {
+    switch (principal) {
+        case "run-sa":
+            return `serviceAccount:${runServiceAccountEmail(install.projectId, install.env)}`;
+        case "gateway-sa":
+            return `serviceAccount:${gatewayServiceAccountEmail(install.projectId, install.env)}`;
+        case "static-publisher-sa":
+            return `serviceAccount:${staticPublisherServiceAccountId(install.env)}@${install.projectId}.iam.gserviceaccount.com`;
+        case "iap-service-agent":
+            return `serviceAccount:service-${install.projectNumber}@gcp-sa-iap.iam.gserviceaccount.com`;
+        case "allUsers":
+            return "allUsers";
+    }
+}
+/** Name prefix of the `gcp` stack's static backend bucket (Pulumi auto-suffixed). */
+export function staticBackendBucketPrefix(env) {
+    return `${gcpNamePrefix(env)}-static-backend`;
+}
+/**
+ * #553 — the admin's memory, in Cloud Run / Kubernetes quantity notation.
+ * The admin runs the quality audit (Lighthouse driving the bundled
+ * Chromium in a child process) next to the editor's requests; 1 GiB left
+ * no headroom for both, 2 GiB does. Every adapter exposes the same
+ * `adminMemory` knob with this default (CLAUDE.md §11.B), and `upgrade`
+ * raises an existing install's admin to it (never lowers a larger value).
+ */
+export const ADMIN_MEMORY_DEFAULT = "2Gi";
+/**
+ * Parse a memory quantity (`512Mi`, `2Gi`, `2G`, `1.5Gi`) to MiB; null when
+ * it is not a quantity this contract understands.
+ */
+/**
+ * #553 — Azure Container Apps (Consumption) only accepts fixed CPU/memory
+ * pairs: 0.25 vCPU / 0.5Gi up to 4 vCPU / 8Gi in 0.25 vCPU steps, memory
+ * always 2 GiB per vCPU. Map `adminMemory` onto that pair, or throw with
+ * the accepted values — an unsupported size must fail before `pulumi up`
+ * does, not deploy something else.
+ */
+export function azureContainerAppResources(quantity) {
+    const mib = memoryQuantityMiB(quantity);
+    if (mib === null || mib % 512 !== 0 || mib < 512 || mib > 8192) {
+        throw new Error(`caelo-azure:adminMemory "${quantity}" is not a Container Apps size; use 0.5Gi to 8Gi in 0.5Gi steps (e.g. 2Gi = 1 vCPU)`);
+    }
+    return { cpu: mib / 2048, memory: `${(mib / 1024).toFixed(1)}Gi` };
+}
+export function memoryQuantityMiB(quantity) {
+    const m = /^(\d+(?:\.\d+)?)\s*(Mi|Gi|M|G)$/.exec(quantity.trim());
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    switch (m[2]) {
+        case "Mi":
+            return Math.round(n);
+        case "Gi":
+            return Math.round(n * 1024);
+        case "M":
+            return Math.round((n * 1000 * 1000) / (1024 * 1024));
+        default:
+            return Math.round((n * 1000 * 1000 * 1000) / (1024 * 1024));
+    }
+}
+//# sourceMappingURL=stack-contract.js.map

package/dist/stack-contract.js.map

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

package/dist/stack-converge.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Converge an existing GCP install to what its Pulumi stack would produce,
+ * through gcloud (`cms-provision upgrade` does not run Pulumi). The desired
+ * state comes from stack-contract.ts, which the stacks use too.
+ *
+ *   - {@link planEnvUpdate}: the env-var flags for the `services update` that
+ *     rolls the image, so env changes ride the same new revision — including
+ *     moving a plain var to a Secret Manager reference.
+ *   - {@link ensureStackInvariants}: IAM bindings + CDN settings. Each binding
+ *     is checked against the resource's policy first and only added when
+ *     missing, so an operator without IAM-admin rights can still upgrade an
+ *     install that is already in shape.
+ */
+import { type GcloudResult } from "./gcloud.js";
+import { type GcloudRunner, type Sleep } from "./gcloud-retry.js";
+import { type CloudRunEnvVar, type CloudRunSlug, type GcpProvider, type ServiceEnvInputs } from "./stack-contract.js";
+/** An env var as a deployed Cloud Run service carries it. */
+export type LiveEnvValue = {
+    readonly kind: "value";
+    readonly value: string;
+} | {
+    readonly kind: "secret";
+    readonly secret: string;
+    readonly version: string;
+};
+/**
+ * Env vars of the first container in `gcloud run services describe
+ * --format=json` output (Knative `serving.knative.dev/v1` Service).
+ */
+export declare function liveContainerEnv(serviceJson: string): Map<string, LiveEnvValue>;
+/** The service account the service's revisions run as (`undefined`: the default compute SA). */
+export declare function liveServiceAccount(serviceJson: string): string | undefined;
+export interface EnvChange {
+    readonly name: string;
+    /** `undefined` when the service does not have the var yet. */
+    readonly from: string | undefined;
+    /** `undefined` when the var is removed. */
+    readonly to: string | undefined;
+}
+export type EnvUpdatePlan = {
+    readonly ok: true;
+    readonly changes: EnvChange[];
+    readonly flags: string[];
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Whether a service still carries a URL with an inline password in a plain
+ * var — the pre-Secret Manager shape. Such a password is in every revision
+ * Cloud Run keeps, so it should be rotated once the services moved off it.
+ */
+export declare function liveEnvHasInlinePassword(liveEnv: ReadonlyMap<string, LiveEnvValue>): boolean;
+/**
+ * The `gcloud run services update` flags that bring `live` to `desired`.
+ * Only vars that differ are touched; vars the contract does not own
+ * (operator additions) are left alone, and the `retired` ones are removed.
+ *
+ * A plain var that becomes a Secret Manager reference moves in the same
+ * update: `--remove-env-vars=X --update-secrets=X=…`. gcloud applies all
+ * literal env changes (removals included) before the secret changes of one
+ * `services update` (googlecloudsdk/command_lib/run/flags.py
+ * `_GetConfigurationChanges`), so the new revision has X as a secret and no
+ * revision is ever without X. The reverse — a secret becoming a plain value
+ * — cannot be expressed in one update (the literal is set while X is still
+ * a secret, which gcloud rejects), so it is refused rather than attempted.
+ */
+export declare function planEnvUpdate(live: ReadonlyMap<string, LiveEnvValue>, desired: readonly CloudRunEnvVar[], retired?: readonly string[]): EnvUpdatePlan;
+/** A deployed Cloud Run service as upgrade found it. */
+export interface DeployedService {
+    /** Pulumi-suffixed service name. */
+    readonly serviceName: string;
+    readonly liveEnv: ReadonlyMap<string, LiveEnvValue>;
+}
+/**
+ * The Cloud SQL host the admin connects to, from its live `ADMIN_DATABASE_URL`
+ * (with or without an inline password — before and after the move to Secret
+ * Manager).
+ */
+export declare function liveDatabaseHost(liveEnv: ReadonlyMap<string, LiveEnvValue>): {
+    ok: true;
+    host: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The env changes that bring both deployed services to their env contract
+ * (stack-contract.ts — the contract the stacks deploy). Values Pulumi
+ * generated at install time (database host, Firebase site) are read from the
+ * live services. Fails instead of guessing when one can't be determined.
+ */
+export declare function planContractEnv(install: ServiceEnvInputs, services: Readonly<Record<CloudRunSlug, DeployedService>>, opts?: {
+    /** Contract vars to leave exactly as the services have them. */
+    readonly leaveUntouched?: readonly string[];
+}): {
+    readonly ok: true;
+    readonly services: Record<CloudRunSlug, {
+        flags: string[];
+        changes: EnvChange[];
+    }>;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** The deployed install `ensureStackInvariants` works on. */
+export interface InstallTarget {
+    readonly provider: GcpProvider;
+    readonly projectId: string;
+    readonly region: string;
+    /** Pulumi stack name (`production`). */
+    readonly env: string;
+    /** Deployed (Pulumi-suffixed) Cloud Run service names. */
+    readonly services: Readonly<Record<CloudRunSlug, string>>;
+}
+export interface InvariantOutcome {
+    /** Human-readable identity, e.g. `roles/run.viewer → serviceAccount:… on gateway`. */
+    readonly id: string;
+    readonly status: "present" | "applied" | "failed";
+    /** What a failure means for the upgrade (from the invariant). */
+    readonly onFailure: "abort" | "warn";
+    readonly why: string;
+    readonly error?: string;
+}
+export interface InvariantsReport {
+    readonly outcomes: InvariantOutcome[];
+    /** True when a failed invariant is one the install cannot work without. */
+    readonly mustAbort: boolean;
+}
+/** Whether an IAM policy (JSON) grants `role` to `member` unconditionally. */
+export declare function policyGrants(policyJson: string, role: string, member: string): boolean;
+/**
+ * Idempotently ensure every IAM binding and CDN setting the install's stack
+ * declares (stack-contract.ts). Additive only — nothing is removed. Never
+ * throws for a gcloud failure; the report says what failed and whether the
+ * upgrade must stop.
+ */
+export declare function ensureStackInvariants(install: InstallTarget, deps?: {
+    run?: GcloudRunner;
+    sleep?: Sleep;
+}): Promise<InvariantsReport>;
+/** The memory limit of the service's container (`512Mi`, `2Gi`), or null
+ *  when the service declares none (Cloud Run then runs it with 512Mi). */
+export declare function liveContainerMemory(serviceJson: string): string | null;
+/**
+ * #553 — raise the admin's memory to the stack's default (it runs the
+ * Lighthouse quality audit). Upgrade only ever RAISES: an operator who set
+ * more keeps it, and a value this contract cannot parse is left alone and
+ * reported, never overwritten blindly.
+ */
+export declare function planAdminMemory(live: string | null, desired?: string): {
+    readonly ok: true;
+    readonly flags: readonly string[];
+    readonly from: string | null;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * The single `gcloud run services update` that rolls a service to a new
+ * image, its run SA and its env changes, so all land in one new revision.
+ */
+export declare function serviceRollArgs(roll: {
+    readonly serviceName: string;
+    readonly region: string;
+    readonly projectId: string;
+    readonly imageRef: string;
+    /** The SA the new revision runs as (stack-contract.ts per-service SAs). */
+    readonly serviceAccount: string;
+    readonly envFlags: readonly string[];
+    /** Resource changes (`--memory=…`) that ride the same revision. */
+    readonly resourceFlags?: readonly string[];
+}): string[];
+/**
+ * Run a roll (`serviceRollArgs`), retrying while it fails only because a
+ * fresh secret binding has not propagated yet. Any other failure returns at
+ * once.
+ */
+export declare function rollService(args: string[], deps?: {
+    run?: GcloudRunner;
+    sleep?: Sleep;
+}): Promise<GcloudResult>;
+//# sourceMappingURL=stack-converge.d.ts.map

package/dist/stack-converge.d.ts.map

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