@caelo-cms/provisioning 0.11.10 → 0.11.12

package/src/stack-contract.ts

@@ -49,6 +49,7 @@ import {
   mcpIapServiceAccountEmail,
   operatorAccessJobResource,
   runServiceAccountEmail,
+  schedulerServiceAccountEmail,
   staticPublisherServiceAccountId,
   upgraderJobResource,
 } from "./gcp-names.js";
@@ -161,6 +162,16 @@ export interface DatabaseUrls<V = string> {
    * state the admin publishes into cms_public.
    */
   readonly public: V;
+  /**
+   * #1329 — admin_role on cms_public_staging: the admin's third pool, for
+   * the staging database's plugin schemas and its half of the projection.
+   */
+  readonly publicStagingAdmin: V;
+  /**
+   * #1329 — public_staging_role on cms_public_staging, the staging
+   * gateway's only pool (served from P3b-2 on). It reaches no live data.
+   */
+  readonly publicStaging: V;
 }
 
 /** Port Cloud SQL Postgres listens on (private IP). */
@@ -191,6 +202,8 @@ export function databaseUrls(host: string): DatabaseUrls {
     admin: url("admin_role", "cms_admin"),
     publicAdmin: url("admin_role", "cms_public"),
     public: url("public_role", "cms_public"),
+    publicStagingAdmin: url("admin_role", "cms_public_staging"),
+    publicStaging: url("public_staging_role", "cms_public_staging"),
   };
 }
 
@@ -238,7 +251,7 @@ export function cloudSqlPrivateDnsName(
 
 /** The database URL vars each service carries (the env contract below sets them). */
 export const DATABASE_URL_VARS = {
-  admin: ["ADMIN_DATABASE_URL", "PUBLIC_ADMIN_DATABASE_URL"],
+  admin: ["ADMIN_DATABASE_URL", "PUBLIC_ADMIN_DATABASE_URL", "PUBLIC_STAGING_ADMIN_DATABASE_URL"],
   gateway: ["PUBLIC_DATABASE_URL"],
   // #1328 — no database login at all. On gcp-firebase the service still
   // carries the gateway's URL until its roll removes it with the rest of
@@ -328,6 +341,54 @@ export const CAPTURE_JOB_ENV_VAR = "CAELO_CAPTURE_JOB";
 export const CAPTURE_BUCKET_ENV_VAR = "CAELO_CAPTURE_BUCKET";
 export const MEDIA_BUCKET_ENV_VAR = "CAELO_MEDIA_BUCKET";
 
+/**
+ * #1140 — the admin env var naming the service account of the scheduler
+ * tick (scheduler-setup.ts): the one IAP identity the admin's
+ * `/api/internal/scheduler/tick` accepts. `upgrade` leaves it untouched when
+ * it could not set the tick up.
+ */
+export const SCHEDULER_SERVICE_ACCOUNT_ENV_VAR = "CAELO_SCHEDULER_SERVICE_ACCOUNT";
+
+/**
+ * #1140 — how often the one scheduler job calls the admin's tick, in
+ * minutes (the `schedulerIntervalMinutes` install knob). Each task's own
+ * cadence lives in the admin's due-table; this only bounds how soon a due
+ * task runs. 1 is Cloud Scheduler's floor; above 15 Cloud Run has stopped
+ * the idle admin, so every tick would pay a cold start without saving
+ * anything (maintainer decision on #1140, 2026-10-26).
+ */
+export const SCHEDULER_INTERVAL_MINUTES = { default: 5, min: 1, max: 15 } as const;
+
+/**
+ * Parse the `schedulerIntervalMinutes` knob. Undefined (not configured) is
+ * the default; anything else must be an integer in the bounds — an
+ * out-of-range or non-numeric value throws (CLAUDE.md §2: no silent
+ * substitute).
+ *
+ * @param raw - the configured value (CLI flag, Pulumi config, install.json).
+ * @param source - names where the value came from, for the error.
+ */
+export function parseSchedulerIntervalMinutes(
+  raw: string | number | undefined,
+  source = "schedulerIntervalMinutes",
+): number {
+  if (raw === undefined || raw === "") return SCHEDULER_INTERVAL_MINUTES.default;
+  const n = typeof raw === "number" ? raw : /^\s*\d+\s*$/.test(raw) ? Number(raw) : Number.NaN;
+  const { min, max } = SCHEDULER_INTERVAL_MINUTES;
+  if (!Number.isInteger(n) || n < min || n > max) {
+    throw new Error(
+      `${source} ${JSON.stringify(raw)} is not a whole number of minutes between ${min} and ${max} (default ${SCHEDULER_INTERVAL_MINUTES.default})`,
+    );
+  }
+  return n;
+}
+
+/** The Cloud Scheduler / cron expression of a tick every `minutes` minutes (UTC). */
+export function schedulerCron(minutes: number): string {
+  const m = parseSchedulerIntervalMinutes(minutes);
+  return m === 1 ? "* * * * *" : `*/${m} * * * *`;
+}
+
 /** Where the admin image ships the static-generator CLI. */
 const GENERATOR_CLI = "/app/apps/static-generator/src/cli.ts";
 
@@ -397,6 +458,8 @@ export function adminMediaVolumeTemplate(volume: MediaVolumeContract) {
 export type RuntimeSecret =
   | "postgres-password"
   | "public-role-password"
+  /** #1329 — public_staging_role's password, the staging gateway's login. */
+  | "public-staging-role-password"
   | "secret-kek"
   | "internal-secret"
   | "tool-approval-secret"
@@ -418,7 +481,7 @@ export type RuntimeSecret =
   | "mcp-oauth-seal-key";
 
 /** The Postgres roles Caelo's services log in as, with their passwords. */
-export type DatabaseRole = "admin_role" | "public_role";
+export type DatabaseRole = "admin_role" | "public_role" | "public_staging_role";
 
 /**
  * Each database role's password secret — one per role (#613), so the
@@ -430,6 +493,8 @@ export type DatabaseRole = "admin_role" | "public_role";
 export const DATABASE_ROLE_SECRET: Readonly<Record<DatabaseRole, RuntimeSecret>> = {
   admin_role: "postgres-password",
   public_role: "public-role-password",
+  // #1329 — its own, so neither gateway can ever log in as the other.
+  public_staging_role: "public-staging-role-password",
 };
 
 /**
@@ -445,6 +510,9 @@ export const CLI_GENERATED_SECRETS = [
   // #613 — the gateway's own role password. Generated (never seeded from
   // `postgres-password`), so the gateway never learns admin_role's.
   "public-role-password",
+  // #1329 — the staging gateway's role password, never shared with the
+  // live gateway's (a test asserts the two public logins share no secret).
+  "public-staging-role-password",
   // #650 — the staging access gate's key: signs "Open staging" links and
   // session cookies, derives the crawler credentials. Read by the admin
   // (issues) and the gateway (verifies).
@@ -457,6 +525,19 @@ export const CLI_GENERATED_SECRETS = [
   "mcp-oauth-seal-key",
 ] as const satisfies readonly RuntimeSecret[];
 
+/**
+ * CLI-generated secrets no running service reads yet, each with what reads
+ * it until then. Everything else in {@link CLI_GENERATED_SECRETS} must be
+ * read by a service (stack-contract.test.ts), so an orphaned secret cannot
+ * ship by accident.
+ */
+export const SECRETS_SET_UP_AHEAD_OF_THEIR_READER: Readonly<
+  Partial<Record<(typeof CLI_GENERATED_SECRETS)[number], string>>
+> = {
+  "public-staging-role-password":
+    "#1329 — public_staging_role's password. The stacks (gcp.sql.User) and the converge (staging-database.ts) set the role's password from it; the staging gateway service (#1330) is its first runtime reader.",
+};
+
 /** A CLI-generated secret's first value: random hex, random base64, or a fixed placeholder. */
 export type GeneratedSecretFormat =
   | { readonly kind: "hex32" }
@@ -473,6 +554,7 @@ export const GENERATED_SECRET_FORMAT: Readonly<
   "internal-secret": { kind: "hex32" },
   "tool-approval-secret": { kind: "hex32" },
   "public-role-password": { kind: "hex32" },
+  "public-staging-role-password": { kind: "hex32" },
   "staging-gate-secret": { kind: "hex32" },
   // The gateway's seal key contract (#806): base64 of exactly 32 bytes.
   "mcp-oauth-seal-key": { kind: "base64-32" },
@@ -510,6 +592,8 @@ export const SERVICE_SECRET_ENV: Readonly<
   admin: {
     ADMIN_DATABASE_PASSWORD: "postgres-password",
     PUBLIC_ADMIN_DATABASE_PASSWORD: "postgres-password",
+    // #1329 — admin_role on the staging database.
+    PUBLIC_STAGING_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).
@@ -747,6 +831,15 @@ function commonEnv(inputs: ServiceEnvInputs): CloudRunEnvVar[] {
  */
 export const TRUSTED_PROXY_HOPS_ENV = "CAELO_TRUSTED_PROXY_HOPS";
 
+/**
+ * #1329 — the env var naming which environment a gateway serves, `live` or
+ * `staging` (apps/api-gateway database-env.ts): its database and login
+ * follow from it, and it refuses anything of the other environment's. The
+ * gateway refuses to boot without it. Every adapter sets `live` on the
+ * gateway it runs today; the staging gateway (P3b-2) gets `staging`.
+ */
+export const GATEWAY_ENVIRONMENT_ENV = "CAELO_GATEWAY_ENVIRONMENT";
+
 /**
  * {@link TRUSTED_PROXY_HOPS_ENV} per provider — a property of each
  * adapter's topology (CLAUDE.md §11.B), so it is declared here once and every
@@ -785,6 +878,9 @@ export const GATEWAY_TRUSTED_PROXY_HOPS: Readonly<Record<SupportedProvider, numb
 export function gatewayEnvContract<V>(inputs: RuntimeEnvInputs<V>): CloudRunEnvVar<V | string>[] {
   return [
     ...commonEnv(inputs),
+    // #1329 — this service is the live site's gateway: it may reach
+    // cms_public as public_role and refuses anything of the staging data.
+    { name: GATEWAY_ENVIRONMENT_ENV, value: "live" },
     { name: TRUSTED_PROXY_HOPS_ENV, value: String(GATEWAY_TRUSTED_PROXY_HOPS[inputs.provider]) },
     { name: "PUBLIC_DATABASE_URL", value: inputs.databaseUrls.public },
     ...secretEnv("gateway", inputs.env),
@@ -900,12 +996,14 @@ export const DEFAULT_MCP_AUTH_PROXY_MAX_INSTANCES = 10;
  * anyone choosing it — billed for every idle minute an instance stayed up.
  *
  * The gateway and the MCP-Auth-Proxy only do work inside requests. The
- * admin still runs its background work (Tier 5: audit worker, importer,
- * plugin cron, GC) on in-process timers that need CPU between requests.
+ * admin's periodic work and plugin workers run on the scheduler tick
+ * (#1140), but the quality audit and the site-import crawl still run on
+ * in-process timers that need CPU between requests (#1359, #1360), and the
+ * plugin runtime heartbeat would read an idling instance as down.
  */
 export const SERVICE_CPU_IDLE: Readonly<Record<CloudRunSlug, boolean>> = {
-  // FIXME(issue #1140): true once the admin's background work no longer
-  // depends on CPU between requests (jobs, scheduler, plugin host).
+  // FIXME(issue #1361): true once nothing in the admin depends on CPU
+  // between requests (the category-A jobs, the heartbeat at request start).
   admin: false,
   gateway: true,
   "mcp-auth-proxy": true,
@@ -1180,6 +1278,9 @@ export function adminEnvContract<V>(inputs: AdminEnvInputs<V>): CloudRunEnvVar<V
     // 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 },
+    // #1329 — admin_role on cms_public_staging: the staging database's
+    // plugin schemas and its half of the projection.
+    { name: "PUBLIC_STAGING_ADMIN_DATABASE_URL", value: inputs.databaseUrls.publicStagingAdmin },
     // #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) },
@@ -1211,6 +1312,12 @@ export function adminEnvContract<V>(inputs: AdminEnvInputs<V>): CloudRunEnvVar<V
     { name: CAPTURE_JOB_ENV_VAR, value: captureJobResource(projectId, inputs.region, env) },
     { name: CAPTURE_BUCKET_ENV_VAR, value: gcpBucketName(projectId, env, "capture") },
     { name: MEDIA_BUCKET_ENV_VAR, value: gcpBucketName(projectId, env, "media") },
+    // #1140 — the only IAP identity the admin's scheduler tick endpoint
+    // accepts (scheduler-setup.ts).
+    {
+      name: SCHEDULER_SERVICE_ACCOUNT_ENV_VAR,
+      value: schedulerServiceAccountEmail(projectId, env),
+    },
     // #914 — where Settings → Google sign-in writes the install's Google
     // sign-in client (add-version only, see the run SA's secretVersionAdder
     // invariant).

package/src/stack-converge-secrets.test.ts

@@ -360,6 +360,8 @@ describe("upgrading a v0.10.35 install: the gateway leaves admin_role (#613)", (
     expect(plan.ok && plan.services.gateway.changes.map((c) => c.name).sort()).toEqual([
       "ADMIN_DATABASE_PASSWORD",
       "ADMIN_DATABASE_URL",
+      // #1329 — the gateway says it is the live site's.
+      "CAELO_GATEWAY_ENVIRONMENT",
       // No remote-MCP env: the broker is the MCP-Auth-Proxy's (#1328).
       // #650 — the staging gate key arrives in the same roll.
       "CAELO_STAGING_GATE_SECRET",

package/src/stack-converge.test.ts

@@ -335,14 +335,16 @@ describe("planContractEnv", () => {
     // #650 — the same roll converges the protected staging domain's host
     // and gate key onto an install that predates it.
     expect(plan.services.admin.flags).toEqual([
-      "--update-env-vars=CAELO_SITE_URL=https://acme.com,MEDIA_ROOT_DIR=/app/apps/admin/data/media,CAELO_MCP_IAP_SERVICE_ACCOUNT=caelo-mcp@acme.iam.gserviceaccount.com,CAELO_OPERATOR_ACCESS_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-operator-access-sync,CAELO_UPGRADER_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-upgrader,CAELO_CONVERGE_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-converge,CAELO_AUDIT_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-audit,CAELO_AUDIT_RESULTS_BUCKET=acme-caelo-production-audit-results,CAELO_CAPTURE_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-capture,CAELO_CAPTURE_BUCKET=acme-caelo-production-capture,CAELO_MEDIA_BUCKET=acme-caelo-production-media,CAELO_OPERATOR_OAUTH_CLIENT_STORE=projects/acme/secrets/caelo-production-operator-oauth-client,CAELO_GATEWAY_SERVICE=caelo-production-data-gateway,CAELO_STAGING_HOST=staging.acme.com",
-      "--update-secrets=CAELO_STAGING_GATE_SECRET=caelo-production-staging-gate-secret:latest",
+      // #1329 — and the staging database's pool onto one that predates it.
+      "--update-env-vars=PUBLIC_STAGING_ADMIN_DATABASE_URL=postgresql://admin_role@db1.p-label.europe-west1.sql-psa.goog:5432/cms_public_staging?sslmode=verify-full&sslrootcert=/etc/caelo/db-ca/cloudsql-global.pem,CAELO_SITE_URL=https://acme.com,MEDIA_ROOT_DIR=/app/apps/admin/data/media,CAELO_MCP_IAP_SERVICE_ACCOUNT=caelo-mcp@acme.iam.gserviceaccount.com,CAELO_OPERATOR_ACCESS_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-operator-access-sync,CAELO_UPGRADER_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-upgrader,CAELO_CONVERGE_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-converge,CAELO_AUDIT_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-audit,CAELO_AUDIT_RESULTS_BUCKET=acme-caelo-production-audit-results,CAELO_CAPTURE_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-capture,CAELO_CAPTURE_BUCKET=acme-caelo-production-capture,CAELO_MEDIA_BUCKET=acme-caelo-production-media,CAELO_SCHEDULER_SERVICE_ACCOUNT=caelo-production-scheduler@acme.iam.gserviceaccount.com,CAELO_OPERATOR_OAUTH_CLIENT_STORE=projects/acme/secrets/caelo-production-operator-oauth-client,CAELO_GATEWAY_SERVICE=caelo-production-data-gateway,CAELO_STAGING_HOST=staging.acme.com",
+      "--update-secrets=PUBLIC_STAGING_ADMIN_DATABASE_PASSWORD=caelo-production-postgres-password:latest,CAELO_STAGING_GATE_SECRET=caelo-production-staging-gate-secret:latest",
     ]);
     // #1328 — the Firebase rewrite follows the data gateway (above), which
     // gets no remote-MCP env.
     expect(plan.services.gateway.flags).toEqual([
-      // The gateway learns which forwarded address is the visitor (#845).
-      "--update-env-vars=CAELO_TRUSTED_PROXY_HOPS=1",
+      // The gateway learns which forwarded address is the visitor (#845),
+      // and (#1329) that it is the live site's.
+      "--update-env-vars=CAELO_GATEWAY_ENVIRONMENT=live,CAELO_TRUSTED_PROXY_HOPS=1",
       "--update-secrets=CAELO_STAGING_GATE_SECRET=caelo-production-staging-gate-secret:latest",
     ]);
     // The old gateway service becomes the proxy in one revision: every

package/src/staging-database.test.ts

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import type { GcloudResult } from "./gcloud.js";
+import type { GcloudRunner } from "./gcloud-retry.js";
+import type { HttpFetch } from "./runtime-secrets.js";
+import { ensureStagingDatabase } from "./staging-database.js";
+
+const ok = (stdout = ""): GcloudResult => ({ ok: true, stdout, stderr: "", exitCode: 0 });
+const fail = (stderr: string): GcloudResult => ({ ok: false, stdout: "", stderr, exitCode: 1 });
+const noSleep = async () => {};
+const install = { projectId: "acme", env: "production", credentials: "operator" } as const;
+
+/** gcloud with an instance `pg-1`, the databases and users given, and a staging password secret. */
+function fakeGcloud(state: { databases: string[]; users: string[] }) {
+  const calls: string[] = [];
+  const run: GcloudRunner = async (args) => {
+    const line = args.join(" ");
+    calls.push(line);
+    if (line.startsWith("sql instances list")) return ok("pg-1\n");
+    if (line.startsWith("sql databases list")) return ok(`${state.databases.join("\n")}\n`);
+    if (line.startsWith("sql users list")) return ok(`${state.users.join("\n")}\n`);
+    if (line.startsWith("sql databases create")) return ok();
+    if (line.startsWith("secrets versions access latest")) return ok("s3cret-staging");
+    if (line.startsWith("auth print-access-token")) return ok("tok\n");
+    return fail(`unexpected: ${line}`);
+  };
+  return { run, calls };
+}
+
+/** The Cloud SQL Admin API, finishing every operation at once. */
+function fakeHttp() {
+  const requests: { method: string; url: string; body?: string }[] = [];
+  const http: HttpFetch = async (url, init) => {
+    requests.push({ method: init.method, url, ...(init.body ? { body: init.body } : {}) });
+    return { ok: true, status: 200, text: async () => JSON.stringify({ status: "DONE" }) };
+  };
+  return { http, requests };
+}
+
+describe("ensureStagingDatabase (#1329)", () => {
+  it("creates the database and the login on an install from before them", async () => {
+    const { run, calls } = fakeGcloud({
+      databases: ["cms_admin", "cms_public"],
+      users: ["admin_role", "public_role"],
+    });
+    const { http, requests } = fakeHttp();
+    const outcomes = await ensureStagingDatabase(install, { run, http, sleep: noSleep });
+    expect(outcomes.map((o) => [o.id, o.status])).toEqual([
+      ["database cms_public_staging", "applied"],
+      ["database role public_staging_role", "applied"],
+    ]);
+    expect(calls).toContain(
+      "sql databases create cms_public_staging --instance=pg-1 --project=acme --quiet",
+    );
+    // The password goes in the request body, read from its own secret.
+    expect(calls).toContain(
+      "secrets versions access latest --secret=caelo-production-public-staging-role-password --project=acme",
+    );
+    expect(requests).toEqual([
+      {
+        method: "POST",
+        url: "https://sqladmin.googleapis.com/v1/projects/acme/instances/pg-1/users",
+        body: JSON.stringify({ name: "public_staging_role", password: "s3cret-staging" }),
+      },
+    ]);
+    expect(calls.some((c) => c.includes("s3cret-staging"))).toBe(false);
+  });
+
+  it("leaves an install that has both alone, re-applying the password", async () => {
+    const { run, calls } = fakeGcloud({
+      databases: ["cms_admin", "cms_public", "cms_public_staging"],
+      users: ["admin_role", "public_role", "public_staging_role"],
+    });
+    const { http, requests } = fakeHttp();
+    const outcomes = await ensureStagingDatabase(install, { run, http, sleep: noSleep });
+    expect(outcomes.map((o) => o.status)).toEqual(["present", "present"]);
+    expect(calls.some((c) => c.startsWith("sql databases create"))).toBe(false);
+    expect(requests.map((r) => [r.method, r.url])).toEqual([
+      [
+        "PUT",
+        "https://sqladmin.googleapis.com/v1/projects/acme/instances/pg-1/users?name=public_staging_role",
+      ],
+    ]);
+  });
+
+  it("reports a refused create with the permission it needs", async () => {
+    const calls: string[] = [];
+    const run: GcloudRunner = async (args) => {
+      const line = args.join(" ");
+      calls.push(line);
+      if (line.startsWith("sql instances list")) return ok("pg-1\n");
+      if (line.startsWith("sql databases list")) return ok("cms_admin\n");
+      if (line.startsWith("sql databases create")) return fail("PERMISSION_DENIED: nope");
+      return ok("public_staging_role\n");
+    };
+    const { http } = fakeHttp();
+    const [db] = await ensureStagingDatabase(install, { run, http, sleep: noSleep });
+    expect(db?.status).toBe("failed");
+    expect(db?.error).toContain("cloudsql.databases.create");
+  });
+
+  it("fails without an instance and creates nothing", async () => {
+    const calls: string[] = [];
+    const run: GcloudRunner = async (args) => {
+      calls.push(args.join(" "));
+      return ok("");
+    };
+    const outcomes = await ensureStagingDatabase(install, { run, sleep: noSleep });
+    expect(outcomes).toHaveLength(1);
+    expect(outcomes[0]?.status).toBe("failed");
+    expect(calls).toHaveLength(1);
+  });
+});

package/src/staging-database.ts

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The staging database on an existing GCP install (issue #1329, gateway
+ * hardening P3b-1, epic #763 E10).
+ *
+ * A new install gets `cms_public_staging` and its gateway login
+ * `public_staging_role` from the stack (`gcp.sql.Database` / `gcp.sql.User`).
+ * An install from before has neither, and an update must bring them
+ * without a terminal (CLAUDE.md §11.C): the converge — `cms-provision
+ * upgrade` or the in-cloud converge job behind Settings → Updates — runs
+ * {@link ensureStagingDatabase} before the migrations, which need the
+ * database (migrate.ts `public-staging`, cms_admin migration 0530).
+ *
+ * Both go through the Cloud SQL Admin API, the way the stack creates them,
+ * so the next `pulumi up` adopts the same objects. The database is created
+ * with gcloud (no secret involved); the user through the Admin API with the
+ * password in the request body (runtime-secrets.ts `ensureDatabaseRolePassword`),
+ * read from its CLI-generated secret `public-staging-role-password`, never
+ * on argv. The Admin API makes the new user a member of cloudsqlsuperuser;
+ * the revoke that follows (public-role-isolation.ts) and the role audit
+ * take care of it, as for public_role. Idempotent: an install that has both
+ * only gets the password re-applied.
+ */
+
+import { findSqlInstance } from "./gateway-credentials.js";
+import { gcloud as defaultGcloud } from "./gcloud.js";
+import { type GcloudRunner, realSleep, runWithRetry, type Sleep } from "./gcloud-retry.js";
+import {
+  type EnsureOutcome,
+  ensureDatabaseRolePassword,
+  type HttpFetch,
+} from "./runtime-secrets.js";
+import { type GcloudCredentials, lookupFailure } from "./upgrade/gcp-lookup.js";
+
+/** The staging site's database (#1329). */
+export const STAGING_DATABASE = "cms_public_staging";
+
+/** The staging gateway's login (#1329). */
+export const STAGING_DATABASE_ROLE = "public_staging_role";
+
+/** The names gcloud lists, one per line. */
+function names(stdout: string): string[] {
+  return stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Create `cms_public_staging` and `public_staging_role` where the install
+ * lacks them, and set the role's password to its secret. Reports instead of
+ * throwing; a `failed` outcome names the next step.
+ */
+export async function ensureStagingDatabase(
+  install: {
+    readonly projectId: string;
+    readonly env: string;
+    readonly credentials: GcloudCredentials;
+  },
+  deps: { readonly run?: GcloudRunner; readonly sleep?: Sleep; readonly http?: HttpFetch } = {},
+): Promise<EnsureOutcome[]> {
+  const run = deps.run ?? defaultGcloud;
+  const sleep = deps.sleep ?? realSleep;
+  const lookup = await findSqlInstance(install, { run });
+  if (lookup.status !== "found") {
+    return [
+      {
+        id: `database ${STAGING_DATABASE}`,
+        status: "failed",
+        error: lookupFailure(lookup, "Cloud SQL instance", install.credentials),
+      },
+    ];
+  }
+  const instance = lookup.name;
+  const where = [`--instance=${instance}`, `--project=${install.projectId}`];
+  return [
+    await ensureDatabase(run, sleep, instance, where),
+    await ensureRole(run, deps, install, instance, where),
+  ];
+}
+
+async function ensureDatabase(
+  run: GcloudRunner,
+  sleep: Sleep,
+  instance: string,
+  where: readonly string[],
+): Promise<EnsureOutcome> {
+  const id = `database ${STAGING_DATABASE}`;
+  const listed = await run(["sql", "databases", "list", ...where, "--format=value(name)"]);
+  if (!listed.ok) {
+    return {
+      id,
+      status: "failed",
+      error: `gcloud sql databases list on ${instance}: ${listed.stderr.trim()}`,
+    };
+  }
+  if (names(listed.stdout).includes(STAGING_DATABASE)) return { id, status: "present" };
+  const created = await runWithRetry(run, sleep, [
+    "sql",
+    "databases",
+    "create",
+    STAGING_DATABASE,
+    ...where,
+    "--quiet",
+  ]);
+  if (!created.ok) {
+    return {
+      id,
+      status: "failed",
+      error: `gcloud sql databases create ${STAGING_DATABASE} on ${instance}: ${created.stderr.trim()}. The account running this needs cloudsql.databases.create on the project; re-run once it has.`,
+    };
+  }
+  return { id, status: "applied", detail: `created on ${instance}` };
+}
+
+async function ensureRole(
+  run: GcloudRunner,
+  deps: { readonly sleep?: Sleep; readonly http?: HttpFetch },
+  install: { readonly projectId: string; readonly env: string },
+  instance: string,
+  where: readonly string[],
+): Promise<EnsureOutcome> {
+  const id = `database role ${STAGING_DATABASE_ROLE}`;
+  const listed = await run(["sql", "users", "list", ...where, "--format=value(name)"]);
+  if (!listed.ok) {
+    return {
+      id,
+      status: "failed",
+      error: `gcloud sql users list on ${instance}: ${listed.stderr.trim()}`,
+    };
+  }
+  const exists = names(listed.stdout).includes(STAGING_DATABASE_ROLE);
+  const outcome = await ensureDatabaseRolePassword(
+    { projectId: install.projectId, env: install.env, sqlInstance: instance },
+    STAGING_DATABASE_ROLE,
+    {
+      run,
+      ...(deps.sleep ? { sleep: deps.sleep } : {}),
+      ...(deps.http ? { http: deps.http } : {}),
+      create: !exists,
+    },
+  );
+  if (outcome.status === "failed") return { ...outcome, id };
+  return exists
+    ? { id, status: "present", detail: "password re-applied" }
+    : { id, status: "applied", detail: `created on ${instance}` };
+}