@caelo-cms/provisioning 0.11.10 → 0.11.12

package/src/gcp-names.ts

@@ -221,6 +221,31 @@ export function captureServiceAccountEmail(projectId: string, env: string): stri
   return `${captureServiceAccountId(env)}@${projectId}.iam.gserviceaccount.com`;
 }
 
+/**
+ * #1140 — account id of the scheduler tick's service account: signs its own
+ * IAP credential and calls the admin's tick endpoint, nothing else
+ * (scheduler-setup.ts). `caelo-production-scheduler` is 26 of the 30
+ * characters an account id may have.
+ */
+export function schedulerServiceAccountId(env: string): string {
+  return `${gcpNamePrefix(env)}-scheduler`;
+}
+
+/** Email of the scheduler tick's service account. */
+export function schedulerServiceAccountEmail(projectId: string, env: string): string {
+  return `${schedulerServiceAccountId(env)}@${projectId}.iam.gserviceaccount.com`;
+}
+
+/** #1140 — the Cloud Workflows workflow one scheduler tick runs (scheduler-setup.ts). */
+export function schedulerWorkflowName(env: string): string {
+  return `${gcpNamePrefix(env)}-scheduler-tick`;
+}
+
+/** #1140 — the Cloud Scheduler job that starts the tick workflow every N minutes. */
+export function schedulerJobName(env: string): string {
+  return `${gcpNamePrefix(env)}-scheduler-tick`;
+}
+
 /**
  * Account id of the upgrader job's own service account: may roll the two
  * Cloud Run services, run the migration job and back up Cloud SQL, never

package/src/index.test.ts

@@ -152,7 +152,7 @@ describe("docker-compose generator", () => {
     const out = generateDockerCompose({
       domain: "example.com",
       postgresPassword: "supersecret",
-      rolePasswords: { admin: "adminpw", public: "publicpw" },
+      rolePasswords: { admin: "adminpw", public: "publicpw", publicStaging: "ps" },
       caeloSecretKek: "0".repeat(64),
       dbTlsServerCertSha256: "abababababababababababababababababababababababababababababababab",
       internalSecret: "i".repeat(48),
@@ -175,7 +175,7 @@ describe("docker-compose generator", () => {
     const out = generateDockerCompose({
       domain: "example.com",
       postgresPassword: "supersecret",
-      rolePasswords: { admin: "adminpw", public: "publicpw" },
+      rolePasswords: { admin: "adminpw", public: "publicpw", publicStaging: "ps" },
       caeloSecretKek: "0".repeat(64),
       dbTlsServerCertSha256: "abababababababababababababababababababababababababababababababab",
       internalSecret: "i".repeat(48),
@@ -201,7 +201,7 @@ describe("docker-compose generator", () => {
     const out = generateDockerCompose({
       domain: "example.com",
       postgresPassword: 'pa"ss',
-      rolePasswords: { admin: "a", public: "b" },
+      rolePasswords: { admin: "a", public: "b", publicStaging: "ps" },
       caeloSecretKek: "0".repeat(64),
       dbTlsServerCertSha256: "abababababababababababababababababababababababababababababababab",
       internalSecret: "i".repeat(48),

package/src/index.ts

@@ -46,12 +46,18 @@ export {
   selfHostedCdnCopy,
 } from "./cdn-copy.js";
 export { type ComposeSpec, generateDockerCompose, type RolePasswords } from "./compose.js";
+export {
+  type ConvergeDatabaseTarget,
+  convergeDatabaseTarget,
+  serverIdentityProblem,
+} from "./converge-db-trust.js";
 export {
   type ConvergeClaim,
   type ConvergeJobDeps,
   type ConvergeQueue,
   type ConvergeUpgradeOutcome,
   runConvergeJob,
+  type SecureDatabaseResult,
 } from "./converge-job.js";
 export { convergeExecutionNameError, gcpConvergeDeps } from "./converge-job-gcp.js";
 export { INFRA_CONTRACT_VERSION } from "./infra-contract.js";

package/src/infra-contract.test.ts

@@ -20,8 +20,8 @@ describe("infrastructure contract steps", () => {
     );
   });
 
-  it("is at 16: public_role revoke (3), URL-map redirects role (4), no gateway cms_admin login (5), ops-bucket list (6), gateway proxy hops (7), quality-audit job (8), converge job (9), remote MCP (10), Google sign-in (11), project-level sign-in client (12), edge security headers (13), capture job (14), database verify-full TLS (15), MCP-Auth-Proxy (16)", () => {
-    expect(INFRA_CONTRACT_VERSION).toBe(16);
+  it("is at 18: public_role revoke (3), URL-map redirects role (4), no gateway cms_admin login (5), ops-bucket list (6), gateway proxy hops (7), quality-audit job (8), converge job (9), remote MCP (10), Google sign-in (11), project-level sign-in client (12), edge security headers (13), capture job (14), database verify-full TLS (15), MCP-Auth-Proxy (16), staging database (17), scheduler tick (18)", () => {
+    expect(INFRA_CONTRACT_VERSION).toBe(18);
     expect(INFRA_CONTRACT_STEPS[3]).toContain("#633");
     expect(INFRA_CONTRACT_STEPS[4]).toContain("#587");
     expect(INFRA_CONTRACT_STEPS[5]).toContain("#635");
@@ -36,6 +36,8 @@ describe("infrastructure contract steps", () => {
     expect(INFRA_CONTRACT_STEPS[14]).toContain("#1217");
     expect(INFRA_CONTRACT_STEPS[15]).toContain("#1338");
     expect(INFRA_CONTRACT_STEPS[16]).toContain("#1328");
+    expect(INFRA_CONTRACT_STEPS[17]).toContain("#1329");
+    expect(INFRA_CONTRACT_STEPS[18]).toContain("#1140");
   });
 
   it("lists the pending steps oldest first", () => {
@@ -46,6 +48,6 @@ describe("infrastructure contract steps", () => {
   });
 
   it("names a version a newer release added by number", () => {
-    expect(infraStepsText(16, 17)).toBe("infrastructure step 17 (see that release's notes)");
+    expect(infraStepsText(18, 19)).toBe("infrastructure step 19 (see that release's notes)");
   });
 });

package/src/infra-contract.ts

@@ -22,7 +22,7 @@
  * whose app-roll references infrastructure an install does not have yet fails
  * at roll time, after migrations ran.
  */
-export const INFRA_CONTRACT_VERSION = 16;
+export const INFRA_CONTRACT_VERSION = 18;
 
 // History (why each bump happened — an install below a number needs the
 // converge that introduced it):
@@ -131,6 +131,25 @@ export const INFRA_CONTRACT_VERSION = 16;
 //       services, accounts, IAM and load-balancer resources — none of which
 //       the in-cloud upgrader may create, and the app-roll rolls three
 //       services from now on.
+//  17 — #1329: staging's own database. The Cloud SQL database
+//       `cms_public_staging`, the Admin API user `public_staging_role` (its
+//       password the new CLI-generated secret `public-staging-role-password`)
+//       and its membership revoke; the admin's PUBLIC_STAGING_ADMIN_DATABASE_URL
+//       and the gateway's CAELO_GATEWAY_ENVIRONMENT. The in-cloud upgrader
+//       may create no database, user or secret, and the new admin and
+//       gateway refuse to start without them. Additive only (converge
+//       release 1 of the gateway hardening): nothing is served from the
+//       staging database yet, so rolling back stays harmless.
+//  18 — #1140: the scheduler tick (scheduler-setup.ts). Its service account
+//       (token creator on itself, workflows.invoker, logWriter, IAP access to
+//       the admin), the Cloud Workflows workflow that signs its IAP JWT and
+//       calls the admin's /api/internal/scheduler/tick, the one Cloud
+//       Scheduler job that starts it every schedulerIntervalMinutes, the
+//       operator-access job's CAELO_OPERATOR_ACCESS_IAP_SERVICE_ACCOUNTS (so
+//       its sync keeps the account on IAP) and CAELO_SCHEDULER_SERVICE_ACCOUNT
+//       on the admin. The new admin runs its periodic work and plugin workers
+//       only on that tick, so an in-cloud upgrader must not roll an install
+//       onto it before the tick exists.
 
 /**
  * What each contract version adds, in operator terms — the upgrader's
@@ -154,6 +173,8 @@ export const INFRA_CONTRACT_STEPS: Readonly<Record<number, string>> = {
   14: "the capture job that takes server-side screenshots outside the admin, its service account, bucket and grants (#1217)",
   15: "verified TLS to the database: Cloud SQL's shared server CA, encrypted connections only, and a private DNS name the services dial (#1338)",
   16: "the MCP sign-in service as its own Cloud Run service with its own account (no database access), the visitor gateway as its own service on Firebase installs, and on Google Cloud load-balancer installs the sign-in service's backend and Cloud Armor rule (#1328)",
+  17: "the staging site's own database and its gateway login, kept apart from the live data (#1329)",
+  18: "the scheduler tick that runs the admin's periodic work and plugin workers every few minutes: its service account, workflow and Cloud Scheduler job, and its IAP access (#1140)",
 };
 
 /**

package/src/install-job.ts

@@ -65,13 +65,22 @@ export const OPS_IMAGE_REPOSITORY =
  * Roles the provisioner needs on top of {@link PROVISIONER_ROLE_LIST} when it
  * runs the install job instead of the operator: the operator-access sync job
  * creates a project custom role and a Cloud Scheduler job (operator-access.ts),
- * and the job's own output has to reach Cloud Logging so the terminal can
+ * the scheduler tick deploys a Cloud Workflows workflow (scheduler-setup.ts,
+ * #1140; the converge job gets the same roles, converge-job-setup.ts), and
+ * the job's own output has to reach Cloud Logging so the terminal can
  * tail it. Granted only to installs that use the job. Not an escalation: the
  * provisioner already holds `resourcemanager.projectIamAdmin`.
+ *
+ * This list is also the converge job's self-grant allowlist
+ * (converge-job-preflight.ts `CONVERGE_SELF_GRANTABLE_ROLES`): a role added
+ * here is granted by the converge job of the release that adds it to an
+ * install that lacks it, with no terminal run. Never add an ownership or
+ * IAM-policy role (the tests refuse `SELF_GRANT_FORBIDDEN_ROLES`).
  */
 export const INSTALL_JOB_ROLES = [
   "roles/iam.roleAdmin",
   "roles/cloudscheduler.admin",
+  "roles/workflows.editor",
   "roles/logging.logWriter",
 ] as const;
 

package/src/install-state.ts

@@ -115,6 +115,13 @@ export interface InstallMetadata {
    * run while it is lower than the release's (upgrade/converge.ts).
    */
   infraContractVersion?: number;
+  /**
+   * #1140 — the `schedulerIntervalMinutes` knob: how often the one Cloud
+   * Scheduler job calls the admin's tick (1–15 minutes; `--scheduler-
+   * interval-minutes` on the wizard). Absent: the default (5,
+   * stack-contract.ts SCHEDULER_INTERVAL_MINUTES).
+   */
+  schedulerIntervalMinutes?: number;
 }
 
 /** The install's staging host: its recorded setting, else the default. */

package/src/lifecycle.ts

@@ -641,6 +641,9 @@ async function upgradeLockedInstall(
       domain: meta.domain,
       stagingHost,
       ownerEmail: meta.ownerEmail,
+      ...(meta.schedulerIntervalMinutes !== undefined
+        ? { schedulerIntervalMinutes: meta.schedulerIntervalMinutes }
+        : {}),
       targetTag,
       infraContractVersion: INFRA_CONTRACT_VERSION,
       skipVerify: opts.skipVerify === true,

package/src/mcp-auth-proxy-setup.test.ts

@@ -190,7 +190,10 @@ describe("ensureReleaseServices", () => {
     let cleaned = false;
     const { run, calls } = fakeGcloud({
       ...accountAndGrants,
-      "run services describe caelo-production-data-gateway": fail("NOT_FOUND: could not be found"),
+      // gcloud's real wording: no NOT_FOUND code (searchVIU, 2026-11-03).
+      "run services describe caelo-production-data-gateway": fail(
+        "ERROR: (gcloud.run.services.describe) Cannot find service [caelo-production-data-gateway]",
+      ),
       "run services list": ok("caelo-production-gateway-bbb\n"),
       "run services describe caelo-production-gateway-bbb": ok(JSON.stringify(OLD_GATEWAY)),
       "run services replace": ok(),
@@ -293,6 +296,35 @@ describe("ensureReleaseServices", () => {
     expect(calls.some((c) => c.startsWith("run "))).toBe(false);
   });
 
+  it("retries a grant while the account it just created has not propagated", async () => {
+    const { run: base, calls } = fakeGcloud({
+      ...accountAndGrants,
+      "run services describe caelo-production-mcp-auth-proxy": ok(
+        "caelo-production-mcp-auth-proxy\n",
+      ),
+    });
+    let refusals = 2;
+    const run: GcloudRunner = async (args, opts) => {
+      if (args[0] === "secrets" && refusals > 0) {
+        refusals -= 1;
+        return fail(
+          `ERROR: (gcloud.secrets.add-iam-policy-binding) Status code: 400. Service account ${PROXY_SA} does not exist..`,
+        );
+      }
+      return base(args, opts);
+    };
+    const pauses: number[] = [];
+    const outcomes = await ensureReleaseServices(gcp, {
+      run,
+      sleep: async (ms) => {
+        pauses.push(ms);
+      },
+    });
+    expect(outcomes.map((o) => o.status)).toEqual(["applied", "present", "present", "present"]);
+    expect(pauses.length).toBe(2);
+    expect(calls.filter((c) => c.startsWith("secrets add-iam-policy-binding"))).toHaveLength(2);
+  });
+
   it("stops at once when the account cannot be read", async () => {
     const { run, calls } = fakeGcloud({
       [`iam service-accounts describe ${PROXY_SA}`]: fail("PERMISSION_DENIED"),

package/src/mcp-auth-proxy-setup.ts

@@ -31,7 +31,7 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { gcloud as defaultGcloud } from "./gcloud.js";
-import type { GcloudRunner } from "./gcloud-retry.js";
+import { type GcloudRunner, realSleep, runWithRetry, type Sleep } from "./gcloud-retry.js";
 import { gcpSecretId, mcpAuthProxyServiceAccountEmail } from "./gcp-names.js";
 import { type EnsureOutcome, ensureMcpAuthProxyServiceAccount } from "./runtime-secrets.js";
 import {
@@ -70,9 +70,13 @@ export interface ReleaseServicesDeps {
     readonly path: string;
     readonly cleanup: () => void;
   };
+  /** Waits between retries of a grant on the account created a moment ago. */
+  readonly sleep?: Sleep;
 }
 
-const NOT_FOUND = /NOT_FOUND|not found|does not exist|could not be found/i;
+// gcloud words a missing Cloud Run service "Cannot find service [<name>]."
+// with no NOT_FOUND code (searchVIU upgrade to v0.11.10, 2026-11-03).
+const NOT_FOUND = /NOT_FOUND|not found|cannot find|does not exist|could not be found/i;
 
 /** Ensure everything {@link ReleaseServicesTarget} needs; outcomes in order, failures included. */
 export async function ensureReleaseServices(
@@ -84,7 +88,7 @@ export async function ensureReleaseServices(
   const account = await ensureMcpAuthProxyServiceAccount(target, { run });
   outcomes.push(account);
   if (account.status === "failed") return outcomes;
-  outcomes.push(...(await ensureMcpAuthProxySecretAccess(target, run)));
+  outcomes.push(...(await ensureMcpAuthProxySecretAccess(target, run, deps.sleep ?? realSleep)));
   if (outcomes.some((o) => o.status === "failed")) return outcomes;
   outcomes.push(
     target.provider === "gcp-firebase"
@@ -103,12 +107,15 @@ export async function ensureReleaseServices(
 async function ensureMcpAuthProxySecretAccess(
   target: Pick<ReleaseServicesTarget, "projectId" | "env">,
   run: GcloudRunner,
+  sleep: Sleep,
 ): Promise<EnsureOutcome[]> {
   const member = `serviceAccount:${mcpAuthProxyServiceAccountEmail(target.projectId, target.env)}`;
   const outcomes: EnsureOutcome[] = [];
   for (const secret of serviceSecrets("mcp-auth-proxy")) {
     const id = `secretAccessor → MCP-Auth-Proxy on ${secret}`;
-    const r = await run([
+    // The account was usually created a moment ago, and IAM answers "does
+    // not exist" until it has propagated: retried, not failed.
+    const r = await runWithRetry(run, sleep, [
       "secrets",
       "add-iam-policy-binding",
       gcpSecretId(target.env, secret),

package/src/migration-runner.ts

@@ -24,6 +24,7 @@ import { green, red } from "kleur/colors";
 import { gcloud as defaultGcloud } from "./gcloud.js";
 import type { GcloudRunner } from "./gcloud-retry.js";
 import { GCP_STACK_ENV, gcpSecretId, runServiceAccountEmail } from "./gcp-names.js";
+import { MIGRATION_TARGETS } from "./migration-targets.js";
 import { databaseUrls, SERVICE_SECRET_ENV } from "./stack-contract.js";
 import { liveContainerEnv, liveDatabaseHost } from "./stack-converge.js";
 
@@ -58,15 +59,19 @@ const NEEDS_UPGRADE =
  */
 export function migrationJobEnvArgs(databaseHost: string, env = GCP_STACK_ENV): string[] {
   const urls = databaseUrls(databaseHost);
-  const passwords = (["ADMIN_DATABASE_PASSWORD", "PUBLIC_ADMIN_DATABASE_PASSWORD"] as const).map(
-    (name) => {
-      const secret = SERVICE_SECRET_ENV.admin[name];
-      if (!secret) throw new Error(`the admin env contract has no ${name}`);
-      return `${name}=${gcpSecretId(env, secret)}:latest`;
-    },
-  );
+  const passwords = (
+    [
+      "ADMIN_DATABASE_PASSWORD",
+      "PUBLIC_ADMIN_DATABASE_PASSWORD",
+      "PUBLIC_STAGING_ADMIN_DATABASE_PASSWORD",
+    ] as const
+  ).map((name) => {
+    const secret = SERVICE_SECRET_ENV.admin[name];
+    if (!secret) throw new Error(`the admin env contract has no ${name}`);
+    return `${name}=${gcpSecretId(env, secret)}:latest`;
+  });
   return [
-    `--set-env-vars=ADMIN_DATABASE_URL=${urls.admin},PUBLIC_ADMIN_DATABASE_URL=${urls.publicAdmin}`,
+    `--set-env-vars=ADMIN_DATABASE_URL=${urls.admin},PUBLIC_ADMIN_DATABASE_URL=${urls.publicAdmin},PUBLIC_STAGING_ADMIN_DATABASE_URL=${urls.publicStagingAdmin}`,
     `--set-secrets=${passwords.join(",")}`,
   ];
 }
@@ -300,7 +305,7 @@ export async function runMigrationsViaCloudRunJob(
     sAdmin.stop(green(`Admin config resolved (${migrationImage.slice(-19)})`));
   }
 
-  for (const target of ["admin", "public"] as const) {
+  for (const target of MIGRATION_TARGETS) {
     const s = spinner();
     s.start(`Applying ${target} migrations via one-shot Cloud Run Job...`);
     // Delete-then-create so each invocation runs with the freshest

package/src/migration-targets.ts

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The targets of `packages/migrations/src/migrate.ts`, in the order every
+ * runner applies them — the GCP migration job (migration-runner.ts), the
+ * self-hosted install and upgrade (self-hosted-start.ts,
+ * self-hosted-upgrade.ts) and the self-hosted stack: cms_admin first (its
+ * role audit covers the whole cluster), then the two public databases,
+ * which run the same cms_public files (#1329: cms_public_staging is the
+ * staging site's twin, with its own gateway login).
+ */
+export const MIGRATION_TARGETS = ["admin", "public", "public-staging"] as const;

package/src/operator-access.test.ts

@@ -205,6 +205,21 @@ describe("ensureOperatorAccessSync", () => {
     );
   });
 
+  it("#1140 — tells the job which service accounts keep IAP access (the scheduler tick)", async () => {
+    const { run, calls } = freshInstall();
+    await ensureOperatorAccessSync(
+      { ...target, iapServiceAccounts: ["caelo-production-scheduler@p.iam.gserviceaccount.com"] },
+      { run, sleep: async () => {} },
+    );
+    const deploy = calls.find((c) => c.slice(0, 3).join(" ") === "run jobs deploy") ?? [];
+    const env = deploy.find((a) => a.startsWith("--set-env-vars=")) ?? "";
+    expect(env).toContain(
+      "|CAELO_OPERATOR_ACCESS_IAP_SERVICE_ACCOUNTS=caelo-production-scheduler@p.iam.gserviceaccount.com",
+    );
+    // The static members stay the install's allowlist (converge-job-gcp.ts compares them).
+    expect(env).toContain("|CAELO_OPERATOR_ACCESS_STATIC_MEMBERS=user:owner@x.com|");
+  });
+
   it("#914 — lets the job read exactly the Google sign-in client's secret, nothing else", async () => {
     const { run, lines } = freshInstall();
     await ensureOperatorAccessSync(target, { run, sleep: async () => {} });

package/src/operator-access.ts

@@ -218,11 +218,22 @@ export interface OperatorAccessSyncTarget {
    * The job reconciles that binding, so anyone missing here loses it.
    */
   readonly mcpSigners?: readonly string[];
+  /**
+   * #1140 — service accounts (besides caelo-mcp) that keep
+   * `roles/iap.httpsResourceAccessor` on the admin: the scheduler tick's
+   * account (scheduler-setup.ts) calls the admin through IAP. The job
+   * reconciles that binding to exactly its members, so anyone missing here
+   * loses it on the next run. Emails, not `serviceAccount:` members.
+   */
+  readonly iapServiceAccounts?: readonly string[];
 }
 
 /** Env var of the sync job listing {@link OperatorAccessSyncTarget.mcpSigners}. */
 export const MCP_SIGNERS_ENV = "CAELO_OPERATOR_ACCESS_MCP_SIGNERS";
 
+/** #1140 — env var of the sync job listing {@link OperatorAccessSyncTarget.iapServiceAccounts}. */
+export const IAP_SERVICE_ACCOUNTS_ENV = "CAELO_OPERATOR_ACCESS_IAP_SERVICE_ACCOUNTS";
+
 /** #914 — env var of the sync job naming the Google sign-in client's secret. */
 export const OPERATOR_OAUTH_CLIENT_SECRET_ENV = "CAELO_OPERATOR_OAUTH_CLIENT_SECRET";
 
@@ -424,6 +435,9 @@ export async function ensureOperatorAccessSync(
     ...(target.mcpSigners && target.mcpSigners.length > 0
       ? [`${MCP_SIGNERS_ENV}=${target.mcpSigners.join(",")}`]
       : []),
+    ...(target.iapServiceAccounts && target.iapServiceAccounts.length > 0
+      ? [`${IAP_SERVICE_ACCOUNTS_ENV}=${target.iapServiceAccounts.join(",")}`]
+      : []),
   ];
   const deploy = await run([
     "run",

package/src/pool-budget-stack.ts

@@ -14,11 +14,14 @@
 
 import {
   computePoolBudget,
+  DEFAULT_STAGING_GATEWAY_MAX_INSTANCES,
   type PoolBudget,
   type PoolBudgetInput,
   poolBudgetEnv,
 } from "@caelo-cms/shared";
 
+export { DEFAULT_STAGING_GATEWAY_MAX_INSTANCES };
+
 /** The adapters that provision a Postgres server. */
 export type BudgetProvider = "gcp" | "gcp-firebase" | "aws" | "azure" | "self-hosted";
 
@@ -84,12 +87,24 @@ export const DEFAULT_MAX_CONNECTIONS: Readonly<Record<BudgetProvider, number>> =
  */
 export const DEFAULT_GATEWAY_MAX_INSTANCES = 10;
 
+/**
+ * Admin instances a GCP or AWS stack lets start (`adminMaxInstances` knob).
+ * Five before #1329; the staging database added the admin's
+ * cms_public_staging pool and the staging gateway to the budget, and on the
+ * default server (100 connections) five instances no longer get the
+ * minimum cms_admin pool. Raising `max_connections` instead was ruled out
+ * for db-f1-micro (docs/dev/connection-budget.md, "#1329").
+ */
+export const DEFAULT_ADMIN_MAX_INSTANCES = 4;
+
 /** The server and scale-out a stack sizes its pools for. */
 export interface StackScale {
   readonly maxConnections: number;
   /** Every instance that opens the admin's pools (admin-side services included). */
   readonly adminMaxInstances: number;
   readonly gatewayMaxInstances: number;
+  /** #1329 — the staging gateway's scale-out ({@link DEFAULT_STAGING_GATEWAY_MAX_INSTANCES}). */
+  readonly stagingGatewayMaxInstances: number;
 }
 
 /** A stack's budget plus the env each service sets from it. */

package/src/pool-budget-stacks.test.ts

@@ -12,8 +12,10 @@ import { resolve } from "node:path";
 import { COMPOSE_POOL_BUDGET } from "./compose.js";
 import {
   type BudgetProvider,
+  DEFAULT_ADMIN_MAX_INSTANCES,
   DEFAULT_GATEWAY_MAX_INSTANCES,
   DEFAULT_MAX_CONNECTIONS,
+  DEFAULT_STAGING_GATEWAY_MAX_INSTANCES,
   stackPoolBudget,
 } from "./pool-budget-stack.js";
 
@@ -21,22 +23,39 @@ const stackSource = (provider: string): string =>
   readFileSync(resolve(import.meta.dir, "..", "stacks", provider, "index.ts"), "utf8");
 
 /** Each stack's default scale-out, as its index.ts reads it. */
-const DEFAULT_SCALE: Record<BudgetProvider, { admin: number; gateway: number }> = {
-  gcp: { admin: 5, gateway: DEFAULT_GATEWAY_MAX_INSTANCES },
-  "gcp-firebase": { admin: 5, gateway: DEFAULT_GATEWAY_MAX_INSTANCES },
-  aws: { admin: 5, gateway: DEFAULT_GATEWAY_MAX_INSTANCES },
+const DEFAULT_SCALE: Record<BudgetProvider, { admin: number; gateway: number; staging: number }> = {
+  gcp: {
+    admin: DEFAULT_ADMIN_MAX_INSTANCES,
+    gateway: DEFAULT_GATEWAY_MAX_INSTANCES,
+    staging: DEFAULT_STAGING_GATEWAY_MAX_INSTANCES,
+  },
+  "gcp-firebase": {
+    admin: DEFAULT_ADMIN_MAX_INSTANCES,
+    gateway: DEFAULT_GATEWAY_MAX_INSTANCES,
+    staging: DEFAULT_STAGING_GATEWAY_MAX_INSTANCES,
+  },
+  aws: {
+    admin: DEFAULT_ADMIN_MAX_INSTANCES,
+    gateway: DEFAULT_GATEWAY_MAX_INSTANCES,
+    staging: DEFAULT_STAGING_GATEWAY_MAX_INSTANCES,
+  },
   // admin + orchestrator + runner apps, 10 replicas each.
-  azure: { admin: 30, gateway: 10 },
-  "self-hosted": { admin: 1, gateway: 1 },
+  azure: { admin: 30, gateway: 10, staging: DEFAULT_STAGING_GATEWAY_MAX_INSTANCES },
+  "self-hosted": { admin: 1, gateway: 1, staging: 1 },
 };
 
-/** [cms_admin pool per admin instance, connections left unassigned]. */
+/**
+ * [cms_admin pool per admin instance, connections left unassigned]. #1329
+ * added the staging gateway and the admin's cms_public_staging pool; the
+ * GCP and AWS stacks start four admin instances instead of five so the
+ * cms_admin pool stays at five (docs/dev/connection-budget.md).
+ */
 const EXPECTED: Record<BudgetProvider, [number, number]> = {
-  gcp: [5, 1],
-  "gcp-firebase": [5, 1],
-  aws: [5, 3],
-  azure: [7, 12],
-  "self-hosted": [77, 0],
+  gcp: [5, 0],
+  "gcp-firebase": [5, 0],
+  aws: [5, 2],
+  azure: [5, 9],
+  "self-hosted": [72, 0],
 };
 
 describe("stack pool budgets at the default config", () => {
@@ -46,7 +65,10 @@ describe("stack pool budgets at the default config", () => {
         maxConnections: DEFAULT_MAX_CONNECTIONS[provider],
         adminMaxInstances: DEFAULT_SCALE[provider].admin,
         gatewayMaxInstances: DEFAULT_SCALE[provider].gateway,
+        stagingGatewayMaxInstances: DEFAULT_SCALE[provider].staging,
       });
+      expect(budget.reserves.map((r) => r.name)).toContain("staging-gateway");
+      expect(budget.reserves.map((r) => r.name)).toContain("admin-public-staging");
       expect([budget.adminPoolMax, budget.unassigned]).toEqual(EXPECTED[provider]);
       expect(env.admin).toEqual([
         { name: "CAELO_DB_POOL_MAX", value: String(EXPECTED[provider][0]) },
@@ -60,8 +82,9 @@ describe("stack pool budgets at the default config", () => {
     expect(() =>
       stackPoolBudget("gcp", {
         maxConnections: 100,
-        adminMaxInstances: 5,
+        adminMaxInstances: 4,
         gatewayMaxInstances: 100,
+        stagingGatewayMaxInstances: 1,
       }),
     ).toThrow(/CONNECTION LIMIT, #1338/);
   });
@@ -75,6 +98,8 @@ describe("stacks set the budget on their services", () => {
       expect(src).toContain("...poolBudget.env.admin");
       expect(src).toContain("...poolBudget.env.gateway");
       expect(src).toContain("maxInstances: gatewayMaxInstances");
+      expect(src).toContain("stagingGatewayMaxInstances: DEFAULT_STAGING_GATEWAY_MAX_INSTANCES");
+      expect(src).toContain('cfg.get("adminMaxInstances") ?? String(DEFAULT_ADMIN_MAX_INSTANCES)');
       expect(src).not.toContain("maxInstances: 100");
     });
   }

package/src/public-role-isolation.test.ts

@@ -25,7 +25,11 @@ function fake(answers: (line: string) => GcloudResult) {
 describe("revokePublicRoleMembershipsArgs (#633)", () => {
   it("revokes every database role of the built-in public_role user", () => {
     expect(
-      revokePublicRoleMembershipsArgs({ projectId: "acme", sqlInstance: "caelo-production-pg-1" }),
+      revokePublicRoleMembershipsArgs({
+        projectId: "acme",
+        sqlInstance: "caelo-production-pg-1",
+        role: "public_role",
+      }),
     ).toEqual([
       "sql",
       "users",
@@ -40,7 +44,12 @@ describe("revokePublicRoleMembershipsArgs (#633)", () => {
   });
 
   it("grants nothing in exchange (no --database-roles)", () => {
-    const args = revokePublicRoleMembershipsArgs({ projectId: "p", sqlInstance: "i" });
+    const args = revokePublicRoleMembershipsArgs({
+      projectId: "p",
+      sqlInstance: "i",
+      role: "public_staging_role",
+    });
+    expect(args[3]).toBe("public_staging_role");
     expect(args.some((a) => a.startsWith("--database-roles"))).toBe(false);
   });
 });
@@ -48,17 +57,18 @@ describe("revokePublicRoleMembershipsArgs (#633)", () => {
 describe("revokePublicRoleMemberships", () => {
   const install = { projectId: "acme", env: "production", credentials: "operator" } as const;
 
-  it("finds the instance, then revokes", async () => {
+  it("finds the instance, then revokes for both gateway logins (#1329)", async () => {
     const { run, calls } = fake((l) => (l.startsWith("sql instances list") ? ok("pg-1\n") : ok()));
     const r = await revokePublicRoleMemberships(install, { run, sleep: noSleep });
     expect(r).toEqual({
-      id: "public_role database role memberships",
+      id: "gateway logins' database role memberships",
       status: "applied",
-      detail: "no database roles left on pg-1",
+      detail: "public_role and public_staging_role hold no database roles on pg-1",
     });
-    expect(calls[1]).toBe(
+    expect(calls.slice(1)).toEqual([
       "sql users assign-roles public_role --instance=pg-1 --type=BUILT_IN --revoke-existing-roles --project=acme --quiet",
-    );
+      "sql users assign-roles public_staging_role --instance=pg-1 --type=BUILT_IN --revoke-existing-roles --project=acme --quiet",
+    ]);
   });
 
   it("is idempotent: a second run issues the same revoke and succeeds", async () => {
@@ -66,7 +76,7 @@ describe("revokePublicRoleMemberships", () => {
     await revokePublicRoleMemberships(install, { run, sleep: noSleep });
     const again = await revokePublicRoleMemberships(install, { run, sleep: noSleep });
     expect(again.status).toBe("applied");
-    expect(calls[1]).toBe(calls[3] as string);
+    expect(calls.slice(4)).toEqual(calls.slice(1, 3));
   });
 
   it("fails without an instance and never calls the revoke", async () => {