@fjall/components-infrastructure 9.0.0 → 10.1.2

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

@@ -1,13 +1,14 @@
 import { AwsLogDriver, ContainerImage, DeploymentLifecycleStage, Secret as EcsSecret } from "aws-cdk-lib/aws-ecs";
 import { Peer, Port, SubnetType } from "aws-cdk-lib/aws-ec2";
 import { Effect, Grant, PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
-import { Annotations, Stack, Token } from "aws-cdk-lib";
+import { Annotations, Aws, Stack, Token } from "aws-cdk-lib";
 import { RetentionDays } from "aws-cdk-lib/aws-logs";
 import { StringParameter } from "aws-cdk-lib/aws-ssm";
 import { Construct } from "constructs";
 import { resolveAlertsTopic } from "../../utils/resolveAlertsTopic.js";
 import { EXPECTED_SCHEMA_VERSION_ENV, EXPECTED_SCHEMA_VERSION_TOOL_ENV, EXPECTED_CH_SCHEMA_VERSION_ENV, isClickHouseDatabase, isDatabase, isRelationalDatabase } from "./interfaces/database.js";
 import { isConnectionConfig } from "../../utils/connector.js";
+import { processConnections } from "../../utils/connections.js";
 import { isMigrationContributor } from "./interfaces/migrationContributor.js";
 import { resolveImportedSecret } from "../../resources/aws/secrets/index.js";
 import App from "../../app.js";
@@ -25,10 +26,12 @@ import { FjallLogger } from "../../utils/validationLogger.js";
 import { VALIDATION_PATTERNS } from "@fjall/generator";
 import { evaluateBakeGuard } from "@fjall/util/docker";
 import { toKebab, buildParameterPath } from "@fjall/util";
+import { SCHEMA_GATE_CH_CA_CERT_ENV, SCHEMA_GATE_CH_DATABASE_ENV, SCHEMA_GATE_CH_URL_ENV, SCHEMA_GATE_CONTAINER_NAME, SCHEMA_GATE_DB_URL_BASE_ENV, SCHEMA_GATE_ECR_REPO_NAME } from "@fjall/util/migration";
+import { CONSTRUCTS_VERSION } from "../../utils/engineCompat.js";
 import { validateEc2ServiceSizing, validateEcsDomainConfig, validateSecretName } from "../../resources/aws/compute/ecsValidation.js";
 import { validateSharedEc2CapacityConfig } from "../../resources/aws/compute/ecsCapacityConfig.js";
 import { COMPUTE_DEFAULTS, collectImportedSecretNames } from "./compute.js";
-import { isHookMigrations } from "./computeEcsTypes.js";
+import { isHookMigrations, normaliseSchemaGate } from "./computeEcsTypes.js";
 export { ScalingType } from "./computeEcsTypes.js";
 import { ScalingType } from "./computeEcsTypes.js";
 export const ECS_CAPACITY_PROVIDER_CONFIG = {
@@ -142,6 +145,34 @@ export function validateEcsProps(props) {
                 throw new Error(`Service '${service.name}': Duplicate container names: ` +
                     `${[...new Set(duplicateContainerNames)].join(", ")}`);
             }
+            // Reserved unconditionally (even under `schemaGate: false`) so the name's
+            // meaning never depends on distant config. Patterns layer ONLY — the
+            // resources layer must accept the materialised gate container this layer
+            // hands it. Contract corpus: `ecs/container-named-fjall-schema-gate`,
+            // rejectedSince 10.0.0.
+            if (service.containers.some((c) => c.name === SCHEMA_GATE_CONTAINER_NAME)) {
+                throw new Error(`Service '${service.name}': container name '${SCHEMA_GATE_CONTAINER_NAME}' ` +
+                    `is reserved for the synthetic schema-gate container. Rename the container.`);
+            }
+        }
+        if (service.migrations?.name === SCHEMA_GATE_CONTAINER_NAME) {
+            throw new Error(`Service '${service.name}': migrations.name '${SCHEMA_GATE_CONTAINER_NAME}' ` +
+                `is reserved for the synthetic schema-gate container. Choose a different name.`);
+        }
+        if (service.serviceType === "worker") {
+            const inboundContainers = (service.containers ?? []).filter((container) => container.port !== undefined || container.portMappings !== undefined);
+            if (inboundContainers.length > 0) {
+                const names = inboundContainers
+                    .map((container) => container.name ?? "<unnamed>")
+                    .join(", ");
+                throw new Error(`Service '${service.name}': serviceType 'worker' declares no inbound surface, ` +
+                    `but container(s) ${names} declare port/portMappings. ` +
+                    `Remove the ports or drop serviceType: 'worker'.`);
+            }
+            if (service.routing !== undefined) {
+                throw new Error(`Service '${service.name}': serviceType 'worker' declares no inbound surface, ` +
+                    `but routing is configured. Remove routing or drop serviceType: 'worker'.`);
+            }
         }
         if (service.capacityProvider === "EC2" && !service.ec2Config) {
             throw new Error(`Service '${service.name}' uses EC2 capacity provider but no ec2Config is defined. ` +
@@ -152,6 +183,13 @@ export function validateEcsProps(props) {
                 "The ec2Config will be ignored unless capacityProvider is set to 'EC2'.");
         }
         validateEc2ServiceSizing(service);
+        if (typeof service.circuitBreaker === "object") {
+            const threshold = service.circuitBreaker.threshold;
+            if (threshold !== undefined &&
+                (!Number.isInteger(threshold) || threshold < 1)) {
+                throw new Error(`Service '${service.name}': circuitBreaker.threshold must be a positive integer (got ${threshold}).`);
+            }
+        }
         if (service.deployment !== undefined) {
             const min = service.deployment.minHealthyPercent;
             const max = service.deployment.maxHealthyPercent;
@@ -227,6 +265,37 @@ export function validateEcsProps(props) {
     }
 }
 const DEFAULT_MIGRATE_CONTAINER_NAME = "migrate";
+/**
+ * How long dependent containers wait for the gate to reach SUCCESS before
+ * giving up (stopping the task pre-RUNNING). ECS declares this on the
+ * depended-ON container. 120s is the verified Fargate ceiling
+ * (design 2026-08-10 § 4); the runner's worst-case retry budget
+ * (3 connects × 10s + 2 sleeps × 5s, PG and CH in parallel) fits inside it.
+ */
+const SCHEMA_GATE_START_TIMEOUT_SECONDS = 120;
+/**
+ * Postgres-family scheme test for the gate's v1 eligibility filter. The URL
+ * base is `getConnectionString()` output whose host may be an unresolved CDK
+ * token, so this checks the literal scheme prefix rather than URL-parsing.
+ */
+function isPostgresUrlBase(urlBase) {
+    return (urlBase.startsWith("postgresql://") || urlBase.startsWith("postgres://"));
+}
+/**
+ * Default gate-image URI: the target account's private ECR mirror of
+ * `@fjall/schema-gate`, tagged with the exact package semver (lockstep with
+ * this constructs package). Composed from CDK pseudo-parameters so one synth
+ * works in every account/region; deploy-core's `ensureSchemaGateImage`
+ * creates/mirrors the repository pre-deploy using the same
+ * `SCHEMA_GATE_ECR_REPO_NAME` derivation. `undefined` when the package
+ * version is unresolvable (broken layout) — the caller warns and skips
+ * materialisation rather than emitting an unpullable URI.
+ */
+function defaultSchemaGateImageUri() {
+    if (CONSTRUCTS_VERSION === undefined)
+        return undefined;
+    return `${Aws.ACCOUNT_ID}.dkr.ecr.${Aws.REGION}.${Aws.URL_SUFFIX}/${SCHEMA_GATE_ECR_REPO_NAME}:${CONSTRUCTS_VERSION}`;
+}
 function lifecycleStageForHookMode(mode) {
     switch (mode) {
         case "lifecycle-hook":
@@ -298,6 +367,9 @@ export function expandMigrationsSugar(service, userContainers) {
     });
     return [migrateContainer, ...wired];
 }
+function schemaGateSubjectLabel(subject) {
+    return subject.subjectLabel ?? `Service '${subject.name}'`;
+}
 /**
  * Resolve the relational database carrying `migrations:` from a service's
  * `connections` graph. Returns `undefined` when no connected database declares
@@ -325,7 +397,7 @@ function resolveMigrationDatabaseForService(service) {
         return undefined;
     if (matches.length > 1) {
         const names = matches.map((d) => d.node.id).join(", ");
-        throw new Error(`Service '${service.name}': connections include two or more relational ` +
+        throw new Error(`${schemaGateSubjectLabel(service)}: connections include two or more relational ` +
             `databases declaring \`migrations:\` (${names}). The schema-version ` +
             `gate cannot inject ${EXPECTED_SCHEMA_VERSION_ENV} unambiguously. ` +
             `Split the service so each consumes a single migrated database, or ` +
@@ -356,7 +428,7 @@ function resolveClickHouseDatabaseForService(service) {
         return undefined;
     if (matches.length > 1) {
         const names = matches.map((d) => d.node.id).join(", ");
-        throw new Error(`Service '${service.name}': connections include two or more ClickHouse ` +
+        throw new Error(`${schemaGateSubjectLabel(service)}: connections include two or more ClickHouse ` +
             `databases declaring \`migrations:\` (${names}). The schema-version ` +
             `gate cannot inject ${EXPECTED_CH_SCHEMA_VERSION_ENV} unambiguously. ` +
             `Split the service so each consumes a single migrated database, or ` +
@@ -364,6 +436,83 @@ function resolveClickHouseDatabaseForService(service) {
     }
     return matches[0];
 }
+/**
+ * Author-wins merge: framework entries land only where the authored map has
+ * no value for the key.
+ */
+function mergeAuthorWins(authored, framework) {
+    const merged = { ...(authored ?? {}) };
+    for (const [k, v] of Object.entries(framework)) {
+        if (merged[k] === undefined)
+            merged[k] = v;
+    }
+    return merged;
+}
+/**
+ * Author-wins merge of the resolved PG schema-version env into an authored
+ * env map. Shared by the service-container path (`buildContainerConfigs`) and
+ * the scheduled-task path (`buildScheduledTaskDefinition`) — coupled values:
+ * the TOOL sibling must ride with VERSION on every surface, including under
+ * an author override, because the runtime gate refuses VERSION-without-TOOL.
+ */
+function mergePgSchemaVersionEnv(params) {
+    const { authored, resolved, subject, annotationsScope } = params;
+    if (resolved === undefined)
+        return authored;
+    const authoredValue = authored?.[EXPECTED_SCHEMA_VERSION_ENV];
+    if (authoredValue !== undefined) {
+        const resolvedValue = resolved[EXPECTED_SCHEMA_VERSION_ENV];
+        if (authoredValue !== resolvedValue && annotationsScope !== undefined) {
+            const gateNote = params.materialisedGateNote
+                ? `The author value wins in this container's env (the app's own ` +
+                    `boot gate reads it), but a materialised schema-gate container ` +
+                    `still enforces the resolved value — set schemaGate: ` +
+                    `{ materialise: false } if the author value must be ` +
+                    `authoritative, or schemaGate: false to silence this warning.`
+                : `The author value wins in this container's env.`;
+            Annotations.of(annotationsScope).addWarning(`${subject}: author-set ${EXPECTED_SCHEMA_VERSION_ENV}` +
+                `='${authoredValue}' overrides the value resolved from the connected ` +
+                `database's \`migrations:\` config ('${resolvedValue}'). ${gateNote}` +
+                ` Note that ` +
+                `${EXPECTED_SCHEMA_VERSION_TOOL_ENV} will still be auto-injected ` +
+                `to ensure the runtime gate passes — both envs must emit together.`);
+        }
+        // Runtime gate rejects startup if VERSION is present but TOOL is absent.
+        return {
+            [EXPECTED_SCHEMA_VERSION_TOOL_ENV]: resolved[EXPECTED_SCHEMA_VERSION_TOOL_ENV],
+            ...authored
+        };
+    }
+    const merged = { ...(authored ?? {}) };
+    if (resolved[EXPECTED_SCHEMA_VERSION_ENV] !== undefined) {
+        merged[EXPECTED_SCHEMA_VERSION_ENV] = resolved[EXPECTED_SCHEMA_VERSION_ENV];
+    }
+    if (resolved[EXPECTED_SCHEMA_VERSION_TOOL_ENV] !== undefined) {
+        merged[EXPECTED_SCHEMA_VERSION_TOOL_ENV] =
+            resolved[EXPECTED_SCHEMA_VERSION_TOOL_ENV];
+    }
+    return merged;
+}
+/**
+ * ClickHouse sibling of `mergePgSchemaVersionEnv` — same author-wins
+ * semantics, same two consuming paths.
+ */
+function mergeChSchemaVersionEnv(params) {
+    const { authored, resolved, subject, annotationsScope } = params;
+    if (resolved === undefined)
+        return authored;
+    const authoredValue = authored?.[EXPECTED_CH_SCHEMA_VERSION_ENV];
+    const resolvedValue = resolved[EXPECTED_CH_SCHEMA_VERSION_ENV];
+    if (authoredValue !== undefined &&
+        authoredValue !== resolvedValue &&
+        annotationsScope !== undefined) {
+        Annotations.of(annotationsScope).addWarning(`${subject}: author-set ${EXPECTED_CH_SCHEMA_VERSION_ENV}` +
+            `='${authoredValue}' overrides the value resolved from the connected ` +
+            `ClickHouse database's \`migrations:\` config ('${resolvedValue}'). The ` +
+            `author value wins; ${params.overrideRemedy}`);
+    }
+    return mergeAuthorWins(authored, resolved);
+}
 function getResourceLabel(resource) {
     if (resource !== null &&
         typeof resource === "object" &&
@@ -570,9 +719,14 @@ function assertMigrationSecretsResolvable(service, effectiveMigrations) {
  * @param annotationsScope Construct used as the source for synth-time
  *                      warnings when the author has set `EXPECTED_SCHEMA_VERSION`
  *                      themselves and the resolved value differs.
+ * @param schemaGate    Resolved spec for the synthetic `fjall-schema-gate`
+ *                      container, or `undefined` when materialisation is off
+ *                      (opted out, ineligible, or nothing to gate). When set,
+ *                      the gate container is prepended and every non-migrate
+ *                      container gains a `dependsOn` SUCCESS edge on it.
  * @internal Exported for testing only
  */
-export function buildContainerConfigs(service, schemaVersionEnv, annotationsScope, chGate) {
+export function buildContainerConfigs(service, schemaVersionEnv, annotationsScope, chGate, schemaGate) {
     const userContainers = service.containers && service.containers.length > 0
         ? service.containers
         : undefined;
@@ -581,61 +735,20 @@ export function buildContainerConfigs(service, schemaVersionEnv, annotationsScop
         : userContainers;
     const chSchemaVersionEnv = chGate?.environment;
     const chGateSecretsImport = chGate?.secretsImport;
-    const mergeSchemaEnv = (authored) => {
-        if (schemaVersionEnv === undefined)
-            return authored;
-        const authoredValue = authored?.[EXPECTED_SCHEMA_VERSION_ENV];
-        if (authoredValue !== undefined) {
-            const resolvedValue = schemaVersionEnv[EXPECTED_SCHEMA_VERSION_ENV];
-            if (authoredValue !== resolvedValue && annotationsScope !== undefined) {
-                Annotations.of(annotationsScope).addWarning(`Service '${service.name}': author-set ${EXPECTED_SCHEMA_VERSION_ENV}` +
-                    `='${authoredValue}' overrides the value resolved from the connected ` +
-                    `database's \`migrations:\` config ('${resolvedValue}'). The author ` +
-                    `value wins; set \`schemaGate: false\` to silence this warning. Note ` +
-                    `that ${EXPECTED_SCHEMA_VERSION_TOOL_ENV} will still be auto-injected ` +
-                    `to ensure the runtime gate passes — both envs must emit together.`);
-            }
-            // Runtime gate rejects startup if VERSION is present but TOOL is absent.
-            return {
-                [EXPECTED_SCHEMA_VERSION_TOOL_ENV]: schemaVersionEnv[EXPECTED_SCHEMA_VERSION_TOOL_ENV],
-                ...authored
-            };
-        }
-        const merged = { ...(authored ?? {}) };
-        if (schemaVersionEnv[EXPECTED_SCHEMA_VERSION_ENV] !== undefined) {
-            merged[EXPECTED_SCHEMA_VERSION_ENV] =
-                schemaVersionEnv[EXPECTED_SCHEMA_VERSION_ENV];
-        }
-        if (schemaVersionEnv[EXPECTED_SCHEMA_VERSION_TOOL_ENV] !== undefined) {
-            merged[EXPECTED_SCHEMA_VERSION_TOOL_ENV] =
-                schemaVersionEnv[EXPECTED_SCHEMA_VERSION_TOOL_ENV];
-        }
-        return merged;
-    };
-    const mergeChSchemaEnv = (authored) => {
-        if (chSchemaVersionEnv === undefined)
-            return authored;
-        const authoredValue = authored?.[EXPECTED_CH_SCHEMA_VERSION_ENV];
-        const resolvedValue = chSchemaVersionEnv[EXPECTED_CH_SCHEMA_VERSION_ENV];
-        if (authoredValue !== undefined) {
-            if (authoredValue !== resolvedValue && annotationsScope !== undefined) {
-                Annotations.of(annotationsScope).addWarning(`Service '${service.name}': author-set ${EXPECTED_CH_SCHEMA_VERSION_ENV}` +
-                    `='${authoredValue}' overrides the value resolved from the connected ` +
-                    `ClickHouse database's \`migrations:\` config ('${resolvedValue}'). The ` +
-                    `author value wins; set \`schemaGate: false\` to silence this warning.`);
-            }
-            return mergeAuthorWins(authored, chSchemaVersionEnv);
-        }
-        return mergeAuthorWins(authored, chSchemaVersionEnv);
-    };
-    const mergeAuthorWins = (authored, framework) => {
-        const merged = { ...(authored ?? {}) };
-        for (const [k, v] of Object.entries(framework)) {
-            if (merged[k] === undefined)
-                merged[k] = v;
-        }
-        return merged;
-    };
+    const mergeSchemaEnv = (authored) => mergePgSchemaVersionEnv({
+        authored,
+        resolved: schemaVersionEnv,
+        subject: `Service '${service.name}'`,
+        annotationsScope,
+        materialisedGateNote: true
+    });
+    const mergeChSchemaEnv = (authored) => mergeChSchemaVersionEnv({
+        authored,
+        resolved: chSchemaVersionEnv,
+        subject: `Service '${service.name}'`,
+        annotationsScope,
+        overrideRemedy: "set `schemaGate: false` to silence this warning."
+    });
     const mergeChGateSecretsImport = (authored) => {
         if (chGateSecretsImport === undefined)
             return authored;
@@ -649,8 +762,49 @@ export function buildContainerConfigs(service, schemaVersionEnv, annotationsScop
         return merged;
     };
     const mergeAllSchemaEnv = (authored) => mergeChSchemaEnv(mergeSchemaEnv(authored));
+    // Prepend the synthetic gate container and wire every other container to
+    // wait on its SUCCESS. In init-container mode the gate itself waits on the
+    // migrate container's SUCCESS (migrate → gate → app); the app containers'
+    // existing migrate dependency stays — redundant but harmless. The migrate
+    // container must NOT depend on the gate (it runs against the pre-migration
+    // schema by definition).
+    const wireSchemaGate = (built) => {
+        if (schemaGate === undefined || built.length === 0)
+            return built;
+        const migrateName = service.migrations !== undefined && !isHookMigrations(service.migrations)
+            ? (service.migrations.name ?? DEFAULT_MIGRATE_CONTAINER_NAME)
+            : undefined;
+        const gateContainer = {
+            name: SCHEMA_GATE_CONTAINER_NAME,
+            image: schemaGate.image,
+            verbatimImage: true,
+            // SUCCESS dependencies require a non-essential target
+            essential: false,
+            environment: schemaGate.environment,
+            ...(Object.keys(schemaGate.secretsImport).length > 0 && {
+                secretsImport: schemaGate.secretsImport
+            }),
+            startTimeout: SCHEMA_GATE_START_TIMEOUT_SECONDS,
+            ...(migrateName !== undefined && {
+                dependsOn: [{ container: migrateName, condition: "SUCCESS" }]
+            })
+        };
+        const wired = built.map((c) => c.name === migrateName
+            ? c
+            : {
+                ...c,
+                dependsOn: [
+                    ...(c.dependsOn ?? []),
+                    {
+                        container: SCHEMA_GATE_CONTAINER_NAME,
+                        condition: "SUCCESS"
+                    }
+                ]
+            });
+        return [gateContainer, ...wired];
+    };
     if (expanded) {
-        return expanded.map((c, index) => {
+        return wireSchemaGate(expanded.map((c, index) => {
             return {
                 name: c.name || `${service.name}Container${index > 0 ? index : ""}`,
                 image: c.image,
@@ -667,11 +821,11 @@ export function buildContainerConfigs(service, schemaVersionEnv, annotationsScop
                 volumes: c.volumes,
                 stopTimeout: c.stopTimeout
             };
-        });
+        }));
     }
     const fallbackEnv = mergeAllSchemaEnv(undefined);
     const fallbackSecretsImport = mergeChGateSecretsImport(undefined);
-    return [
+    return wireSchemaGate([
         {
             name: `${service.name}Container`,
             ...(fallbackEnv !== undefined && { environment: fallbackEnv }),
@@ -679,7 +833,7 @@ export function buildContainerConfigs(service, schemaVersionEnv, annotationsScop
                 secretsImport: fallbackSecretsImport
             })
         }
-    ];
+    ]);
 }
 function resolveMigrationImage(svcConfig, migrations, inheritedImage) {
     if (migrations.image !== undefined)
@@ -741,15 +895,30 @@ export class EcsCompute extends Construct {
     clusterId;
     appName;
     migrationTaskDefinitions = new Map();
+    /**
+     * Service name → exact `@fjall/schema-gate` semver, for every service that
+     * materialised the gate container with the DEFAULT image this synth.
+     * ComputeFactory copies it onto the manifest entry (`schemaGateImageTag`)
+     * so deploy-core's `ensureSchemaGateImage` mirrors the tag pre-deploy.
+     * BYO-image services (`schemaGate.image`) are deliberately absent — the
+     * author owns that image's availability.
+     */
+    schemaGateImageTags;
     constructor(scope, id, props) {
         super(scope, id);
         validateEcsProps(props);
         this.clusterId = id;
         this.appName = props.appName;
+        const schemaGateImageTags = new Map();
+        this.schemaGateImageTags = schemaGateImageTags;
         const services = props.services.map((service) => {
             const schemaVersionEnv = this.resolveSchemaVersionEnv(service);
             const chGate = this.resolveClickHouseSchemaVersionEnv(service);
-            const containers = buildContainerConfigs(service, schemaVersionEnv, this, chGate);
+            const schemaGateSpec = this.resolveSchemaGateMaterialisation(service, schemaVersionEnv, chGate);
+            if (schemaGateSpec?.defaultImageTag !== undefined) {
+                schemaGateImageTags.set(service.name, schemaGateSpec.defaultImageTag);
+            }
+            const containers = buildContainerConfigs(service, schemaVersionEnv, this, chGate, schemaGateSpec);
             const { scalingType, minCapacity, maxCapacity, queueScaling } = resolveScalingConfig(service.scaling);
             const cloudMapService = service.serviceDiscovery !== undefined
                 ? App.getInstance().registerService({
@@ -818,7 +987,8 @@ export class EcsCompute extends Construct {
             cluster,
             services,
             alertsTopic: resolvedAlertsTopic,
-            applicationId: props.applicationId
+            applicationId: props.applicationId,
+            ...(props.taskStopWatchdog === false && { taskStopWatchdog: false })
         };
         this.ecsCluster = new EcsCluster(this, `${id}Ecs`, ecsProps);
         this.connections = this.ecsCluster.connections;
@@ -842,7 +1012,7 @@ export class EcsCompute extends Construct {
      * hardcoding one.
      */
     resolveSchemaVersionEnv(service) {
-        if (service.schemaGate === false)
+        if (!normaliseSchemaGate(service.schemaGate).envInjection)
             return undefined;
         const db = resolveMigrationDatabaseForService(service);
         if (db === undefined)
@@ -852,7 +1022,7 @@ export class EcsCompute extends Construct {
             return undefined;
         const config = db.getMigrationsConfig();
         if (config === undefined) {
-            throw new Error(`Service '${service.name}': schema-version-gate produced a version ` +
+            throw new Error(`${schemaGateSubjectLabel(service)}: schema-version-gate produced a version ` +
                 `but the connected database returned no migrations config — these ` +
                 `must move together.`);
         }
@@ -877,7 +1047,7 @@ export class EcsCompute extends Construct {
      * - Two or more migrated CHs → throws via `resolveClickHouseDatabaseForService`
      */
     resolveClickHouseSchemaVersionEnv(service) {
-        if (service.schemaGate === false)
+        if (!normaliseSchemaGate(service.schemaGate).envInjection)
             return undefined;
         const db = resolveClickHouseDatabaseForService(service);
         if (db === undefined)
@@ -896,6 +1066,120 @@ export class EcsCompute extends Construct {
         }
         return { environment, secretsImport };
     }
+    /**
+     * Decide whether the synthetic `fjall-schema-gate` container materialises
+     * for this service, and compose its env/secrets/image when it does.
+     * Returns `undefined` (env-injection-only, the pre-10.x behaviour) when:
+     *
+     * - `schemaGate: false` or `{ materialise: false }` (author opt-out)
+     * - Neither a PG nor a CH gate resolved for the service
+     * - `migrations.mode: "post-deploy"` — expected is deliberately ahead of
+     *   the DB during scale-up, so a materialised gate would refuse every task
+     *   (synth warning)
+     * - `migrations.mode: "lifecycle-hook"` WITHOUT `separateTaskDef` — the
+     *   hook's migration RunTask reuses the service task definition, so a
+     *   materialised gate would refuse the migration task itself while the DB
+     *   still holds the pre-migration schema (synth warning; adding
+     *   `separateTaskDef` restores full gating)
+     * - No eligible half survives the v1 scope filters: the relational half
+     *   requires `tool: "prisma"` and a postgres-family connection scheme
+     *   (per-half synth warnings; env injection into app containers stays on)
+     * - 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.
+     */
+    resolveSchemaGateMaterialisation(service, schemaVersionEnv, chGate) {
+        const normalised = normaliseSchemaGate(service.schemaGate);
+        if (!normalised.materialise)
+            return undefined;
+        if (schemaVersionEnv === undefined && chGate === undefined) {
+            return undefined;
+        }
+        if (service.migrations?.mode === "post-deploy") {
+            Annotations.of(this).addWarning(`Service '${service.name}': schema-gate materialisation is disabled ` +
+                `because migrations.mode is "post-deploy" — the expected schema ` +
+                `version is deliberately ahead of the database while new tasks ` +
+                `scale up, so a materialised gate would refuse every task. ` +
+                `Env injection stays on. Set schemaGate: false to silence.`);
+            return undefined;
+        }
+        if (service.migrations?.mode === "lifecycle-hook" &&
+            service.migrations.separateTaskDef === undefined) {
+            Annotations.of(this).addWarning(`Service '${service.name}': schema-gate materialisation is disabled ` +
+                `because migrations.mode is "lifecycle-hook" without ` +
+                `separateTaskDef — the migration RunTask reuses the service task ` +
+                `definition, so a materialised gate would refuse the migration ` +
+                `task itself during the pre-migration window. Add ` +
+                `migrations.separateTaskDef to run migrations in their own task ` +
+                `definition and restore full gating. Env injection stays on.`);
+            return undefined;
+        }
+        const environment = {};
+        const secretsImport = {};
+        let eligibleHalves = 0;
+        if (schemaVersionEnv !== undefined) {
+            const tool = schemaVersionEnv[EXPECTED_SCHEMA_VERSION_TOOL_ENV];
+            const db = resolveMigrationDatabaseForService(service);
+            const contribution = db?.getSchemaGateContribution();
+            const urlBase = contribution?.environment[SCHEMA_GATE_DB_URL_BASE_ENV];
+            if (tool !== "prisma") {
+                Annotations.of(this).addWarning(`Service '${service.name}': the materialised schema gate cannot ` +
+                    `verify migrations.tool "${tool ?? "<unset>"}" (v1 supports ` +
+                    `"prisma" only) — the relational half is skipped. Env injection ` +
+                    `into app containers stays on.`);
+            }
+            else if (contribution === undefined ||
+                urlBase === undefined ||
+                !isPostgresUrlBase(urlBase)) {
+                Annotations.of(this).addWarning(`Service '${service.name}': the materialised schema gate supports ` +
+                    `postgres-family databases only (v1) — the relational half is ` +
+                    `skipped. Env injection into app containers stays on.`);
+            }
+            else {
+                Object.assign(environment, schemaVersionEnv, contribution.environment);
+                Object.assign(secretsImport, contribution.secretsImport);
+                eligibleHalves += 1;
+            }
+        }
+        if (chGate !== undefined) {
+            const db = resolveClickHouseDatabaseForService(service);
+            if (db !== undefined) {
+                Object.assign(environment, chGate.environment, {
+                    [SCHEMA_GATE_CH_URL_ENV]: db.getUrl(),
+                    [SCHEMA_GATE_CH_DATABASE_ENV]: db.getDatabaseName()
+                });
+                Object.assign(secretsImport, chGate.secretsImport);
+                const caCert = db.getTlsCaCertImport();
+                if (caCert !== undefined) {
+                    secretsImport[SCHEMA_GATE_CH_CA_CERT_ENV] = caCert;
+                }
+                eligibleHalves += 1;
+            }
+        }
+        if (eligibleHalves === 0)
+            return undefined;
+        if (normalised.image !== undefined) {
+            return { environment, secretsImport, image: normalised.image };
+        }
+        const defaultImage = defaultSchemaGateImageUri();
+        if (defaultImage === undefined || CONSTRUCTS_VERSION === undefined) {
+            Annotations.of(this).addWarning(`Service '${service.name}': schema-gate materialisation is disabled ` +
+                `because the constructs package version could not be resolved for ` +
+                `the default gate image tag. Set schemaGate.image explicitly.`);
+            return undefined;
+        }
+        return {
+            environment,
+            secretsImport,
+            image: defaultImage,
+            defaultImageTag: CONSTRUCTS_VERSION
+        };
+    }
     materialiseScheduledTasks(id, props) {
         const scheduledTasks = props.cluster?.scheduledTasks;
         if (!scheduledTasks || scheduledTasks.length === 0)
@@ -947,14 +1231,24 @@ export class EcsCompute extends Construct {
             streamPrefix: `/ecs-scheduled/${id}/${entry.name}`,
             logGroup
         });
+        const { environment, secrets } = this.composeScheduledTaskEnvAndSecrets(id, entry);
         const container = taskDef.addContainer(`${id}${toPascalCase(entry.name)}Container`, {
             image: entry.image,
             cpu: entry.cpu,
             memoryLimitMiB: entry.memoryLimitMiB,
             ...(entry.command !== undefined && { command: entry.command }),
-            ...(entry.secrets !== undefined && { secrets: entry.secrets }),
+            ...(environment !== undefined && { environment }),
+            ...(secrets !== undefined && { secrets }),
             logging
         });
+        if (entry.connections !== undefined && entry.connections.length > 0) {
+            try {
+                processConnections(entry.connections, taskDef.taskRole, this.ecsCluster.getEc2CapacityConnectable());
+            }
+            catch (error) {
+                throw new Error(`Failed to process connections for scheduled task '${entry.name}': ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+            }
+        }
         if (entry.volumes) {
             for (const volume of entry.volumes) {
                 container.addMountPoints({
@@ -966,6 +1260,91 @@ export class EcsCompute extends Construct {
         }
         return taskDef;
     }
+    /**
+     * Compose a scheduled task's container env and secrets: schema-version gate
+     * env resolved from the entry's `connections` merges beneath the author's
+     * `environment` (author wins — the same semantics as service containers),
+     * and the ClickHouse gate's credential imports merge beneath the author's
+     * `secrets`. Returns `undefined` halves when nothing applies so the
+     * container definition stays byte-identical for unconnected entries.
+     */
+    composeScheduledTaskEnvAndSecrets(id, entry) {
+        const subject = `Scheduled task '${entry.name}'`;
+        const gateSubject = {
+            name: entry.name,
+            subjectLabel: subject,
+            connections: entry.connections,
+            schemaGate: entry.schemaGate
+        };
+        const schemaVersionEnv = this.resolveSchemaVersionEnv(gateSubject);
+        const chGate = this.resolveClickHouseSchemaVersionEnv(gateSubject);
+        const environment = mergeChSchemaVersionEnv({
+            authored: mergePgSchemaVersionEnv({
+                authored: entry.environment,
+                resolved: schemaVersionEnv,
+                subject,
+                annotationsScope: this,
+                materialisedGateNote: false
+            }),
+            resolved: chGate?.environment,
+            subject,
+            annotationsScope: this,
+            overrideRemedy: "remove the env entry to accept the resolved value."
+        });
+        let secrets = entry.secrets;
+        if (chGate !== undefined && Object.keys(chGate.secretsImport).length > 0) {
+            const merged = {};
+            for (const [key, secretImport] of Object.entries(chGate.secretsImport)) {
+                if (entry.secrets?.[key] !== undefined)
+                    continue;
+                const secret = resolveImportedSecret(this, `${id}${toPascalCase(entry.name)}${key}Secret`, secretImport);
+                merged[key] = EcsSecret.fromSecretsManager(secret, secretImport.field);
+            }
+            secrets = { ...merged, ...(entry.secrets ?? {}) };
+        }
+        return { environment, secrets };
+    }
+    /**
+     * A sibling service that consumes a hook-migrated database materialises a
+     * schema gate that refuses while the owner's migration is still in flight.
+     * Without `awaitMigrationsFrom` the sibling rolls out in parallel with the
+     * owner, so its gate-refused task churn can trip the deployment circuit
+     * breaker before the migration lands. The gate refusing is by design (new
+     * code must not serve the old schema); the missing DependsOn is the
+     * author-fixable part — warn, don't disable.
+     */
+    warnUngatedSiblingsOfHookOwners(services) {
+        for (const owner of services) {
+            const ownerMigrations = owner.migrations;
+            if (!ownerMigrations || !isHookMigrations(ownerMigrations))
+                continue;
+            const ownerDb = resolveMigrationDatabaseForService(owner);
+            const ownerCh = resolveClickHouseDatabaseForService(owner);
+            if (ownerDb === undefined && ownerCh === undefined)
+                continue;
+            for (const sibling of services) {
+                if (sibling.name === owner.name)
+                    continue;
+                if (sibling.awaitMigrationsFrom === owner.name)
+                    continue;
+                if (!normaliseSchemaGate(sibling.schemaGate).materialise)
+                    continue;
+                const sharesDb = ownerDb !== undefined &&
+                    resolveMigrationDatabaseForService(sibling) === ownerDb;
+                const sharesCh = ownerCh !== undefined &&
+                    resolveClickHouseDatabaseForService(sibling) === ownerCh;
+                if (!sharesDb && !sharesCh)
+                    continue;
+                Annotations.of(this).addWarning(`Service '${sibling.name}': consumes a database whose migrations ` +
+                    `run via service '${owner.name}''s deployment hook, but does ` +
+                    `not declare awaitMigrationsFrom: "${owner.name}". Its ` +
+                    `materialised schema gate will refuse tasks that scale up ` +
+                    `before the migration lands, which can trip the deployment ` +
+                    `circuit breaker. Add awaitMigrationsFrom to order the ` +
+                    `rollouts, or set schemaGate: { materialise: false }.`);
+            }
+        }
+    }
     /**
      * For each service whose `migrations.mode` is a lambda-hook variant
      * (`"lifecycle-hook"` for PRE_SCALE_UP, `"post-deploy"` for POST_SCALE_UP),
@@ -975,6 +1354,7 @@ export class EcsCompute extends Construct {
      * migrate container injected by `expandMigrationsSugar`.
      */
     wireLifecycleHookMigrations(services) {
+        this.warnUngatedSiblingsOfHookOwners(services);
         for (const svcConfig of services) {
             const migrations = svcConfig.migrations;
             if (!migrations || !isHookMigrations(migrations))