@fjall/components-infrastructure 19.0.0 → 21.0.0

package/README.md

@@ -2,6 +2,56 @@
 
 Published fjall infrastructure components and utilities.
 
+## Upgrade notes
+
+### 21.0.0 — ClickHouse identities by workload class (breaking)
+
+`ClickHouseDatabase` no longer shares one `schemaAdmin` principal across the
+migration task, the schema gate and the maintenance sidecars. Each workload
+class now authenticates as its own identity, so no two classes contend for
+the same `max_concurrent_queries_for_user` cap:
+
+| identity                  | holder                        |
+| ------------------------- | ----------------------------- |
+| `schemaAdmin.name` (XML)  | migration task ONLY           |
+| `fjall_schema_gate` (SQL) | materialised gate container   |
+| `fjall_maintenance` (SQL) | OPTIMIZE FINAL + BACKUP tasks |
+
+What changes in a synthesised stack:
+
+- **App containers lose `SCHEMA_ADMIN_USER` / `SCHEMA_ADMIN_PASSWORD`.** They
+  keep `EXPECTED_CH_SCHEMA_VERSION`. A container image that runs its own
+  in-process ClickHouse schema check reading those two variables must drop
+  it — the materialised gate container performs the check.
+- **The gate container authenticates as `fjall_schema_gate`** via
+  `FJALL_SCHEMA_GATE_CH_USER` / `FJALL_SCHEMA_GATE_CH_PASSWORD` (read-only,
+  `SELECT` on `<db>._schema_migrations` only).
+- **The OPTIMIZE and BACKUP scheduled tasks authenticate as
+  `fjall_maintenance`.** Their execution roles read that identity's secret,
+  not the schema admin's. Both scripts open with a migrate ↔ maintenance
+  activity pre-flight and log `fjall:maintenance:status=<ok|deferred|failed>`
+  markers; `status=failed` pages via a new `ClickHouseMaintenanceFailedAlarm`.
+- **Two new fixed-name Secrets Manager secrets** —
+  `fjall/clickhouse/fjall-schema-gate-password` and
+  `fjall/clickhouse/fjall-maintenance-password` — are minted by the construct.
+  They are NOT injected into the ClickHouse service container, so the
+  ClickHouse service task definition is unchanged by the upgrade.
+- **The `fjall_` user-name prefix is reserved.** A `schemaAdmin.name` or
+  `managedPasswords` entry starting with `fjall_` fails synth.
+
+Deploy order: the identities are SQL-provisioned by the migration runner
+(`@fjall/clickhouse` 21 — bump the migration image before this construct),
+so the migration task must run once under 21.x BEFORE anything authenticates
+as the new identities. Deploy the Database stack, then the Compute stack that
+carries the migration task, and only then let the schedules fire.
+
+Rollback: rolling back to 20.x deletes the two framework secrets, which
+Secrets Manager only schedules (30-day recovery window). Re-adopting 21.x
+inside that window fails on the held names — first run
+`aws secretsmanager restore-secret --secret-id fjall/clickhouse/<name>-password`
+or `aws secretsmanager delete-secret --secret-id … --force-delete-without-recovery`
+for each of the two secrets.
+
 ## Useful commands
 
 - `npm run build` compile typescript to js

package/dist/lib/patterns/aws/clickhouseDatabase.d.ts

@@ -192,8 +192,12 @@ export interface ClickHouseDatabaseProps {
      * `<access_management>1</access_management>` so it can manage GRANT /
      * CREATE USER from SQL. `profile` MUST name a key in `profiles:` (or
      * `ClickHouseDefaultProfiles`) and is bound directly via the XML config.
-     * Scheduled tasks (OPTIMIZE FINAL, BACKUP DATABASE) authenticate as this
-     * user — one set of credentials, one IAM grant chain.
+     * The migration task is the ONLY holder: the scheduled tasks (OPTIMIZE
+     * FINAL, BACKUP DATABASE) authenticate as the framework's
+     * `fjall_maintenance` identity and the materialised schema gate as
+     * `fjall_schema_gate`, both SQL-provisioned by the migration runner from
+     * `getMigrationContributions()`. The name must not start with the
+     * reserved `fjall_` prefix.
      */
     schemaAdmin: ClickHouseSchemaAdmin;
     /**
@@ -241,7 +245,9 @@ export interface ClickHouseDatabaseProps {
     /**
      * Ops alarm SNS topic for the full ClickHouse alarm surface: host-posture
      * alarms (CPU / disk warn+critical), the ECS-layer service alarms (cgroup
-     * memory, `RunningTaskCount` liveness, task-stop watchdog), the server-log
+     * memory, `RunningTaskCount` liveness — which enables Container Insights on
+     * the inner cluster, ~$0.30/metric-month — and the task-stop watchdog), the
+     * server-log
      * signal alarms (errors, failed queries, backpressure, cold-tier S3), and —
      * when `backupSchedule` is enabled — the backup-failure alarm plus the
      * backup success heartbeat (absence + arming-gate alarms and the paging
@@ -376,8 +382,22 @@ export declare class ClickHouseDatabase extends Construct implements IClickHouse
      * `process.env`. The helper reads the env vars directly — no runtime
      * `secretsmanager:GetSecretValue` SDK call is needed; ECS executionRole
      * carries the IAM grant via the standard `secretsImport` framework path.
+     *
+     * **Framework identities.** `FJALL_CLICKHOUSE_USERS` (the gate and
+     * maintenance identities) ship the same way under their own manifest,
+     * `CLICKHOUSE_FRAMEWORK_USERS`, each with a `USER_<NAME>_PASSWORD` import,
+     * plus `CLICKHOUSE_MAINTENANCE_PROFILE` naming the schema admin's settings
+     * profile so the runner can bind `fjall_maintenance` to the same
+     * instance-scaled caps without knowing any numbers.
      */
     getMigrationContributions(): MigrationContributions;
+    /**
+     * The materialised gate's ClickHouse credentials: the gate authenticates as
+     * the read-only `fjall_schema_gate` identity, never as the schema admin.
+     * Env `FJALL_SCHEMA_GATE_CH_USER` carries the fixed name; secret
+     * `FJALL_SCHEMA_GATE_CH_PASSWORD` imports that identity's password.
+     * `undefined` when no `migrations:` config is declared — nothing to gate.
+     */
     getSchemaGateContribution(): {
         readonly environment: Record<string, string>;
         readonly secretsImport: Record<string, SecretImport>;

package/dist/lib/patterns/aws/clickhouseDatabase.js

@@ -1,4 +1,4 @@
-import { CLICKHOUSE_MANAGED_USERS_ENV, pickLatestClickHouseMigration, SCHEMA_ADMIN_PASSWORD_ENV, SCHEMA_ADMIN_USER_ENV } from "@fjall/util/migration";
+import { CLICKHOUSE_FRAMEWORK_USERS_ENV, CLICKHOUSE_MAINTENANCE_PROFILE_ENV, CLICKHOUSE_MANAGED_USERS_ENV, FJALL_CLICKHOUSE_USER_PREFIX, FJALL_CLICKHOUSE_USERS, FJALL_MAINTENANCE_USER, FJALL_SCHEMA_GATE_USER, isReservedClickHouseUserName, pickLatestClickHouseMigration, SCHEMA_ADMIN_PASSWORD_ENV, SCHEMA_ADMIN_USER_ENV, SCHEMA_GATE_CH_PASSWORD_ENV, SCHEMA_GATE_CH_USER_ENV } from "@fjall/util/migration";
 import { Annotations, CfnOutput, Duration, Fn, Stack } from "aws-cdk-lib";
 import { Connections, Port, UserData } from "aws-cdk-lib/aws-ec2";
 import { Monitoring } from "aws-cdk-lib/aws-autoscaling";
@@ -16,6 +16,7 @@ import { S3Bucket } from "../../resources/aws/storage/s3.js";
 import { Secret } from "../../resources/aws/secrets/secret.js";
 import { LogGroup } from "../../resources/aws/logging/logGroup.js";
 import { createClickHouseSecurityGroup } from "../../resources/aws/database/clickhouseSecurityGroup.js";
+import { buildMaintenancePreamble, maintenanceOkMarker, maintenanceRun } from "../../resources/aws/database/clickhouseMaintenanceScript.js";
 import { buildClickHouseEntrypointWrapper, buildClickHouseUserData, generateUsersConfigXml } from "../../resources/aws/database/clickhouseUserData.js";
 import { toPascalCase } from "../../utils/capitaliseString.js";
 import { resolveAlertsTopic } from "../../utils/resolveAlertsTopic.js";
@@ -154,6 +155,21 @@ function expectDefined(value, invariant) {
     }
     return value;
 }
+/**
+ * Mints the password secret for one ClickHouse user — customer-declared
+ * (`schemaAdmin`, `managedPasswords`) and framework-owned
+ * (`FJALL_CLICKHOUSE_USERS`) alike, so every identity has the same removal
+ * policy and the same fixed `fjall/clickhouse/<name>-password` name.
+ *
+ * Fixed names carry a rollback cure. A rollback to a constructs version
+ * without the framework identities deletes their secrets, which Secrets
+ * Manager only SCHEDULES (30-day recovery window); re-adopting the identities
+ * inside that window fails with `ResourceExistsException` because the name
+ * is still held by the scheduled-for-deletion secret. Before re-deploying,
+ * either restore it (`aws secretsmanager restore-secret --secret-id
+ * fjall/clickhouse/<name>-password`, then let CloudFormation import) or
+ * remove it outright (`aws secretsmanager delete-secret --secret-id … --force-delete-without-recovery`).
+ */
 function createClickHouseUserSecret(scope, name) {
     return new Secret(scope, `ClickHouseUser${toPascalCase(name)}`, {
         secretName: clickHouseUserSecretName(name),
@@ -202,6 +218,7 @@ export class ClickHouseDatabase extends Construct {
     #httpPort;
     #nativePort;
     #users;
+    #frameworkSecrets;
     #schemaAdmin;
     #managedPasswordNames;
     #backupBucket;
@@ -259,6 +276,12 @@ export class ClickHouseDatabase extends Construct {
             }
             seenNames.add(name);
         }
+        for (const name of seenNames) {
+            if (isReservedClickHouseUserName(name)) {
+                throw new Error(`ClickHouseDatabase: user name '${name}' uses the reserved '${FJALL_CLICKHOUSE_USER_PREFIX}' prefix — ` +
+                    `framework identities (${FJALL_CLICKHOUSE_USERS.join(", ")}) are provisioned by the framework and cannot be declared in schemaAdmin or managedPasswords`);
+            }
+        }
         const allUserNames = [
             schemaAdmin.name,
             ...managedPasswords
@@ -328,7 +351,16 @@ export class ClickHouseDatabase extends Construct {
         for (const name of allUserNames) {
             userSecrets.set(name, createClickHouseUserSecret(this, name));
         }
+        // Framework identities are minted OUTSIDE `userSecrets`: they are never
+        // injected into the ClickHouse service container (the migration runner
+        // provisions them over SQL), never exposed via `getUser`, and never
+        // declared as stack outputs — adopting them changes no service task def.
+        const frameworkSecrets = new Map();
+        for (const name of FJALL_CLICKHOUSE_USERS) {
+            frameworkSecrets.set(name, createClickHouseUserSecret(this, name));
+        }
         this.#users = userSecrets;
+        this.#frameworkSecrets = frameworkSecrets;
         this.#schemaAdmin = schemaAdmin;
         this.#managedPasswordNames = managedPasswords;
         const backupBucket = props.backupBucket ??
@@ -358,6 +390,13 @@ export class ClickHouseDatabase extends Construct {
                 retention: RetentionDays.TWO_WEEKS
             })
             : undefined;
+        // Explicit rather than `logRetention` so the maintenance-status metric
+        // filters can attach to it alongside the backup task's group.
+        const optimiseTaskLogGroup = optimiseEnabled
+            ? new LogGroup(this, "ClickHouseOptimiseTaskLogGroup", {
+                retention: RetentionDays.ONE_WEEK
+            })
+            : undefined;
         // Resolved BEFORE the user data is built: the declared volume size is
         // embedded into the script so a storageGb change versions the launch
         // template (see `dataVolumeSizeGb` on BuildClickHouseUserDataOptions).
@@ -416,10 +455,17 @@ export class ClickHouseDatabase extends Construct {
         const clickHouseHost = this.getHostEndpoint();
         const backupDestUrl = `https://${backupBucket.bucketName}.s3.${Stack.of(this).region}.amazonaws.com/backup/`;
         const optimiseStatements = [
-            ...REPLACING_MERGE_TREE_TABLES.map((table) => `OPTIMIZE TABLE ${CLICKHOUSE_DATABASE_NAME}.${table} FINAL`),
-            ...OPTIMISE_MV_TABLES.map((table) => `OPTIMIZE TABLE ${CLICKHOUSE_DATABASE_NAME}.${table}`)
+            ...REPLACING_MERGE_TREE_TABLES.map((table) => ({
+                table,
+                sql: `OPTIMIZE TABLE ${CLICKHOUSE_DATABASE_NAME}.${table} FINAL`
+            })),
+            ...OPTIMISE_MV_TABLES.map((table) => ({
+                table,
+                sql: `OPTIMIZE TABLE ${CLICKHOUSE_DATABASE_NAME}.${table}`
+            }))
         ];
         const adminSecret = expectDefined(userSecrets.get(schemaAdmin.name), `schemaAdmin '${schemaAdmin.name}' secret not minted.`);
+        const maintenanceSecret = expectDefined(frameworkSecrets.get(FJALL_MAINTENANCE_USER), `framework identity '${FJALL_MAINTENANCE_USER}' secret not minted.`);
         const sidecarTlsPreamble = tlsActive
             ? `set -eu && printf '%s\\n' "$CLICKHOUSE_CA_CERT" > /tmp/ca.crt && printf '%s' '<?xml version="1.0"?><config><openSSL><client><caConfig>/tmp/ca.crt</caConfig><verificationMode>strict</verificationMode><loadDefaultCAFile>false</loadDefaultCAFile><invalidCertificateHandler><name>RejectCertificateHandler</name></invalidCertificateHandler></client></openSSL></config>' > /tmp/clickhouse-client.xml && `
             : "";
@@ -432,33 +478,49 @@ export class ClickHouseDatabase extends Construct {
         // One clickhouse-client invocation per statement: a single multi-statement
         // --query aborts on the first failure, so one missing table (a migration
         // deploy-order window, or a dropped table lingering in the constants)
-        // would permanently skip every optimise after it. Failures are logged and
-        // the task still exits non-zero so they stay visible in the task history.
-        // Both scheduled tasks authenticate identically; the password arrives via
-        // CLICKHOUSE_PASSWORD rather than argv.
-        const clickHouseClient = `clickhouse-client --host ${clickHouseHost} --port ${nativePort} --user ${schemaAdmin.name}${sidecarTlsClientArgs}`;
+        // would permanently skip every optimise after it. Each failure emits its
+        // own status marker and the task still exits non-zero so they stay
+        // visible in the task history. Both scheduled tasks authenticate as the
+        // maintenance identity; the password arrives via CLICKHOUSE_PASSWORD
+        // rather than argv.
+        const clickHouseClient = `clickhouse-client --host ${clickHouseHost} --port ${nativePort} --user ${FJALL_MAINTENANCE_USER}${sidecarTlsClientArgs}`;
         const optimiseScript = [
             "FAILED=0",
-            ...optimiseStatements.map((stmt) => `${clickHouseClient} --query "${stmt}" || { echo "optimise failed: ${stmt}"; FAILED=1; }`),
+            ...optimiseStatements.map(({ table, sql }) => `${maintenanceRun(`optimise_${table}`, sql)} || FAILED=1`),
+            `if [ "$FAILED" = 0 ]; then ${maintenanceOkMarker("optimise")}; fi`,
             'exit "$FAILED"'
         ].join("; ");
-        // Resolved before the scheduled tasks because the backup task's
+        const optimisePreamble = buildMaintenancePreamble({
+            client: clickHouseClient,
+            job: "optimise",
+            schemaAdminName: schemaAdmin.name
+        });
+        const maintenanceSecrets = {
+            CLICKHOUSE_PASSWORD: EcsSecret.fromSecretsManager(maintenanceSecret.secret, "password"),
+            ...sidecarTlsSecrets
+        };
         const scheduledTasks = [];
-        if (optimiseEnabled) {
+        const maintenanceLogGroups = [];
+        if (optimiseEnabled && optimiseTaskLogGroup !== undefined) {
             scheduledTasks.push({
                 name: "ClickHouseOptimiseTask",
                 schedule: optimiseSchedule,
                 image: ContainerImage.fromRegistry(CLICKHOUSE_IMAGE),
                 cpu: OPTIMISE_TASK_CPU_UNITS,
                 memoryLimitMiB: OPTIMISE_TASK_MEMORY_MIB,
-                command: ["sh", "-c", `${sidecarTlsPreamble}${optimiseScript}`],
-                secrets: {
-                    CLICKHOUSE_PASSWORD: EcsSecret.fromSecretsManager(adminSecret.secret, "password"),
-                    ...sidecarTlsSecrets
-                },
-                logRetention: RetentionDays.ONE_WEEK,
+                command: [
+                    "sh",
+                    "-c",
+                    `${sidecarTlsPreamble}${optimisePreamble}\n${optimiseScript}`
+                ],
+                secrets: maintenanceSecrets,
+                logGroup: optimiseTaskLogGroup,
                 securityGroups: [securityGroup]
             });
+            maintenanceLogGroups.push({
+                job: "optimise",
+                logGroup: optimiseTaskLogGroup
+            });
         }
         if (backupEnabled && backupTaskLogGroup !== undefined) {
             scheduledTasks.push({
@@ -473,6 +535,7 @@ export class ClickHouseDatabase extends Construct {
                     // Password via CLICKHOUSE_PASSWORD env, not --password on argv (argv → /proc/<pid>/cmdline).
                     `${sidecarTlsPreamble}${buildClickHouseBackupScript({
                         client: clickHouseClient,
+                        schemaAdminName: schemaAdmin.name,
                         databaseName: CLICKHOUSE_DATABASE_NAME,
                         backupDestUrl,
                         diskFreeCriticalGib,
@@ -480,13 +543,14 @@ export class ClickHouseDatabase extends Construct {
                         verify: backupVerifyEnabled
                     })}`
                 ],
-                secrets: {
-                    CLICKHOUSE_PASSWORD: EcsSecret.fromSecretsManager(adminSecret.secret, "password"),
-                    ...sidecarTlsSecrets
-                },
+                secrets: maintenanceSecrets,
                 logGroup: backupTaskLogGroup,
                 securityGroups: [securityGroup]
             });
+            maintenanceLogGroups.push({
+                job: "backup",
+                logGroup: backupTaskLogGroup
+            });
         }
         const clickHouseContainerSecrets = {};
         for (const name of allUserNames) {
@@ -505,7 +569,11 @@ export class ClickHouseDatabase extends Construct {
             type: "ecs",
             vpc,
             ...(resolvedAlertsTopic !== undefined && {
-                alertsTopic: resolvedAlertsTopic
+                alertsTopic: resolvedAlertsTopic,
+                // `RunningTaskCount` liveness exists only under Container Insights;
+                // enabled together with the alarm surface so the documented liveness
+                // alarm has a metric to watch (and costs nothing when alarms are off).
+                containerInsights: true
             }),
             ...(applicationId !== undefined && { applicationId }),
             cluster: {
@@ -697,6 +765,7 @@ export class ClickHouseDatabase extends Construct {
                 config: alarmThresholds,
                 diskFreeCriticalGib,
                 backupVerifyEnabled,
+                maintenanceLogGroups,
                 ...(applicationId !== undefined && { applicationId }),
                 ...(backupTaskLogGroup !== undefined && { backupTaskLogGroup })
             });
@@ -900,17 +969,31 @@ export class ClickHouseDatabase extends Construct {
      * `process.env`. The helper reads the env vars directly — no runtime
      * `secretsmanager:GetSecretValue` SDK call is needed; ECS executionRole
      * carries the IAM grant via the standard `secretsImport` framework path.
+     *
+     * **Framework identities.** `FJALL_CLICKHOUSE_USERS` (the gate and
+     * maintenance identities) ship the same way under their own manifest,
+     * `CLICKHOUSE_FRAMEWORK_USERS`, each with a `USER_<NAME>_PASSWORD` import,
+     * plus `CLICKHOUSE_MAINTENANCE_PROFILE` naming the schema admin's settings
+     * profile so the runner can bind `fjall_maintenance` to the same
+     * instance-scaled caps without knowing any numbers.
      */
     getMigrationContributions() {
         const environment = {
             CLICKHOUSE_URL: this.getUrl(),
             CLICKHOUSE_DATABASE: this.getDatabaseName(),
-            [SCHEMA_ADMIN_USER_ENV]: this.#schemaAdmin.name
+            [SCHEMA_ADMIN_USER_ENV]: this.#schemaAdmin.name,
+            [CLICKHOUSE_MAINTENANCE_PROFILE_ENV]: this.#schemaAdmin.profile
         };
         const secretsImport = {};
         const adminSecret = this.getUser(this.#schemaAdmin.name);
         secretsImport[SCHEMA_ADMIN_PASSWORD_ENV] =
             adminSecret.getImport("password");
+        for (const [name, secret] of this.#frameworkSecrets) {
+            secretsImport[userPasswordEnvName(name)] = secret.getImport("password");
+        }
+        environment[CLICKHOUSE_FRAMEWORK_USERS_ENV] = JSON.stringify([
+            ...FJALL_CLICKHOUSE_USERS
+        ]);
         const caCertImport = this.getTlsCaCertImport();
         if (caCertImport !== undefined) {
             secretsImport.CLICKHOUSE_CA_CERT = caCertImport;
@@ -942,16 +1025,23 @@ export class ClickHouseDatabase extends Construct {
         }
         return { environment, secretsImport, egress };
     }
+    /**
+     * The materialised gate's ClickHouse credentials: the gate authenticates as
+     * the read-only `fjall_schema_gate` identity, never as the schema admin.
+     * Env `FJALL_SCHEMA_GATE_CH_USER` carries the fixed name; secret
+     * `FJALL_SCHEMA_GATE_CH_PASSWORD` imports that identity's password.
+     * `undefined` when no `migrations:` config is declared — nothing to gate.
+     */
     getSchemaGateContribution() {
         if (this.#migrationsConfig === undefined)
             return undefined;
-        const adminSecret = this.getUser(this.#schemaAdmin.name);
+        const gateSecret = expectDefined(this.#frameworkSecrets.get(FJALL_SCHEMA_GATE_USER), `framework identity '${FJALL_SCHEMA_GATE_USER}' secret not minted.`);
         return {
             environment: {
-                [SCHEMA_ADMIN_USER_ENV]: this.#schemaAdmin.name
+                [SCHEMA_GATE_CH_USER_ENV]: FJALL_SCHEMA_GATE_USER
             },
             secretsImport: {
-                [SCHEMA_ADMIN_PASSWORD_ENV]: adminSecret.getImport("password")
+                [SCHEMA_GATE_CH_PASSWORD_ENV]: gateSecret.getImport("password")
             }
         };
     }

package/dist/lib/patterns/aws/computeEcs.d.ts

@@ -72,10 +72,7 @@ export declare function expandMigrationsSugar(service: EcsServiceConfig, userCon
  *                      container gains a `dependsOn` SUCCESS edge on it.
  * @internal Exported for testing only
  */
-export declare function buildContainerConfigs(service: EcsServiceConfig, schemaVersionEnv?: Record<string, string>, annotationsScope?: Construct, chGate?: {
-    environment: Record<string, string>;
-    secretsImport: Record<string, SecretImport>;
-}, schemaGate?: SchemaGateContainerSpec): EcsClusterProps["services"][number]["containers"];
+export declare function buildContainerConfigs(service: EcsServiceConfig, schemaVersionEnv?: Record<string, string>, annotationsScope?: Construct, chSchemaVersionEnv?: Record<string, string>, schemaGate?: SchemaGateContainerSpec): EcsClusterProps["services"][number]["containers"];
 /**
  * Resolved scaling configuration for an ECS service.
  * @internal Exported for testing only
@@ -131,17 +128,16 @@ export declare class EcsCompute extends Construct implements IEcsCompute {
     private resolveSchemaVersionEnv;
     /**
      * ClickHouse mirror of `resolveSchemaVersionEnv`. Returns the
-     * `EXPECTED_CH_SCHEMA_VERSION` env entry alongside the schema-admin
-     * credentials the boot gate needs to authenticate against
-     * `_schema_migrations`, or `undefined` when the service is not gated.
+     * `EXPECTED_CH_SCHEMA_VERSION` env entry, or `undefined` when the service
+     * is not gated. Env only: app containers receive no ClickHouse credentials
+     * from the gate — the materialised gate container authenticates as the
+     * read-only gate identity via `getSchemaGateContribution()`, composed in
+     * `resolveSchemaGateMaterialisation`.
      *
      * - `schemaGate: false` → returns `undefined` (auditable opt-out — same flag
      *   covers BOTH PG and CH gates)
      * - No migrated CH in connections → returns `undefined`
-     * - Exactly one migrated CH → returns env `EXPECTED_CH_SCHEMA_VERSION` +
-     *   `SCHEMA_ADMIN_USER`, plus `secretsImport.SCHEMA_ADMIN_PASSWORD`. The
-     *   creds piggyback on the same gate resolution so adding the gate to a
-     *   service can't ship without the creds it needs to use it.
+     * - Exactly one migrated CH → returns `{ EXPECTED_CH_SCHEMA_VERSION }`
      * - Two or more migrated CHs → throws via `resolveClickHouseDatabaseForService`
      */
     private resolveClickHouseSchemaVersionEnv;
@@ -166,11 +162,13 @@ export declare class EcsCompute extends Construct implements IEcsCompute {
      * - The default image URI cannot be derived because the constructs package
      *   version is unresolvable and no `schemaGate.image` override is set
      *
-     * The relational half re-resolves the migrated DB for its
-     * `getSchemaGateContribution()` (credential-free URL base + user/password
-     * secret imports). The CH half composes `CLICKHOUSE_URL` / database name /
-     * CA-cert import from the resolved CH database — `chGate` alone carries
-     * only the version + schema-admin entries the app containers get.
+     * Both halves re-resolve the migrated DB for its
+     * `getSchemaGateContribution()`: the relational half for the
+     * credential-free URL base + user/password secret imports, the CH half for
+     * the read-only gate identity (`FJALL_SCHEMA_GATE_CH_USER` +
+     * `FJALL_SCHEMA_GATE_CH_PASSWORD`) composed with `CLICKHOUSE_URL` /
+     * database name / CA-cert import — `chSchemaVersionEnv` alone carries only
+     * the version entry the app containers get.
      */
     private resolveSchemaGateMaterialisation;
     private materialiseScheduledTasks;