@fjall/components-infrastructure 0.95.0 → 0.99.1

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

@@ -1,12 +1,30 @@
-import { Grant } from "aws-cdk-lib/aws-iam";
-import { Fn } from "aws-cdk-lib";
+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 } from "aws-cdk-lib";
+import { RetentionDays } from "aws-cdk-lib/aws-logs";
+import { Secret } from "aws-cdk-lib/aws-secretsmanager";
+import { StringParameter } from "aws-cdk-lib/aws-ssm";
 import { Construct } from "constructs";
-import { Topic } from "aws-cdk-lib/aws-sns";
-import EcsCluster, { ScalingType } from "../../resources/aws/compute/ecs.js";
+import { resolveAlertsTopic } from "../../utils/resolveAlertsTopic.js";
+import { EXPECTED_SCHEMA_VERSION_ENV, EXPECTED_SCHEMA_VERSION_TOOL_ENV, isDatabase, isRelationalDatabase } from "./interfaces/database.js";
+import { isConnectionConfig } from "../../utils/connector.js";
+import { isMigrationContributor } from "./interfaces/migrationContributor.js";
+import App from "../../app.js";
+import EcsCluster from "../../resources/aws/compute/ecs.js";
+import { createScheduledTaskDefinition, createMigrationTaskDefinition } from "../../resources/aws/compute/ecsTaskDefinition.js";
+import { EcsLifecycleHookMigration } from "../../resources/aws/compute/ecsLifecycleHookMigration.js";
+import { Role } from "../../resources/aws/iam/role.js";
+import { LogGroup } from "../../resources/aws/logging/logGroup.js";
+import { SecurityGroup } from "../../resources/aws/networking/securityGroup.js";
+import { vpcHasNatGateways } from "../../utils/vpcUtils.js";
+import { toPascalCase } from "../../utils/capitaliseString.js";
 import { FjallLogger } from "../../utils/validationLogger.js";
+import { VALIDATION_PATTERNS } from "@fjall/generator";
 import { COMPUTE_DEFAULTS } from "./compute.js";
-// Re-export from ecs.ts to maintain single source of truth
-export { ScalingType };
+import { isHookMigrations } from "./computeEcsTypes.js";
+export { ScalingType } from "./computeEcsTypes.js";
+import { ScalingType } from "./computeEcsTypes.js";
 export const ECS_CAPACITY_PROVIDER_CONFIG = {
     FARGATE: {
         usesSpot: false,
@@ -24,6 +42,35 @@ export const ECS_CAPACITY_PROVIDER_CONFIG = {
 export function getEcsCapacityProviderConfig(provider) {
     return ECS_CAPACITY_PROVIDER_CONFIG[provider];
 }
+/**
+ * Fargate task-size matrix (CPU → valid memory range in MiB).
+ *
+ * @see https://docs.aws.amazon.com/AmazonECS/latest/developerguide/fargate-tasks-services.html#fargate-tasks-size
+ */
+const FARGATE_CPU_MEMORY_MATRIX = {
+    256: { min: 512, max: 2048 },
+    512: { min: 1024, max: 4096 },
+    1024: { min: 2048, max: 8192 },
+    2048: { min: 4096, max: 16384 },
+    4096: { min: 8192, max: 30720 },
+    8192: { min: 16384, max: 61440 },
+    16384: { min: 32768, max: 122880 }
+};
+const FARGATE_VALID_CPUS = Object.keys(FARGATE_CPU_MEMORY_MATRIX)
+    .map((k) => parseInt(k, 10))
+    .sort((a, b) => a - b);
+function validateSeparateTaskDef(serviceName, separateTaskDef) {
+    const matrix = FARGATE_CPU_MEMORY_MATRIX[separateTaskDef.cpu];
+    if (!matrix) {
+        throw new Error(`Service '${serviceName}': migrations.separateTaskDef.cpu must be one of ${FARGATE_VALID_CPUS.join(", ")} ` +
+            `(got ${separateTaskDef.cpu}). See AWS Fargate task-size matrix.`);
+    }
+    if (separateTaskDef.memoryLimitMiB < matrix.min ||
+        separateTaskDef.memoryLimitMiB > matrix.max) {
+        throw new Error(`Service '${serviceName}': migrations.separateTaskDef.memoryLimitMiB (${separateTaskDef.memoryLimitMiB}) ` +
+            `is incompatible with cpu=${separateTaskDef.cpu} (allowed range: ${matrix.min}-${matrix.max} MiB).`);
+    }
+}
 /**
  * Validates ECS-specific props.
  * Extracted for clarity and detail parity with database/network patterns.
@@ -40,7 +87,7 @@ export function validateEcsProps(props) {
         throw new Error(`Duplicate service names: ${[...new Set(duplicateNames)].join(", ")}`);
     }
     // Validate service name format
-    const invalidNames = props.services.filter((s) => !/^[a-zA-Z][a-zA-Z0-9-]*$/.test(s.name));
+    const invalidNames = props.services.filter((s) => !VALIDATION_PATTERNS.ECS_SERVICE_NAME.test(s.name));
     if (invalidNames.length > 0) {
         throw new Error(`Invalid service names: ${invalidNames.map((s) => s.name).join(", ")}. ` +
             "Service names must start with a letter and contain only letters, numbers, and hyphens.");
@@ -79,35 +126,397 @@ export function validateEcsProps(props) {
             throw new Error(`Service '${service.name}' uses EC2 capacity provider but no ec2Config is defined. ` +
                 "Provide ec2Config on the service.");
         }
-        // Warn if service ec2Config is defined but capacityProvider is not EC2
         if (service.ec2Config && service.capacityProvider !== "EC2") {
             FjallLogger.warn(`Service '${service.name}' has ec2Config but capacityProvider is not 'EC2'. ` +
                 "The ec2Config will be ignored unless capacityProvider is set to 'EC2'.");
         }
+        if (service.deployment !== undefined) {
+            const min = service.deployment.minHealthyPercent;
+            const max = service.deployment.maxHealthyPercent;
+            if (min !== undefined && (min < 0 || min > 100)) {
+                throw new Error(`Service '${service.name}': deployment.minHealthyPercent must be between 0 and 100 (got ${min}).`);
+            }
+            if (max !== undefined && (max < 100 || max > 200)) {
+                throw new Error(`Service '${service.name}': deployment.maxHealthyPercent must be between 100 and 200 (got ${max}).`);
+            }
+            if (min !== undefined && max !== undefined && min > max) {
+                throw new Error(`Service '${service.name}': deployment.minHealthyPercent (${min}) must be <= maxHealthyPercent (${max}).`);
+            }
+            if (min === 100 && max === 100) {
+                throw new Error(`Service '${service.name}': deployment.minHealthyPercent and maxHealthyPercent cannot both be 100 ` +
+                    "(no capacity to drain or expand — deploys would never roll forward).");
+            }
+        }
+        if (service.migrations !== undefined &&
+            isHookMigrations(service.migrations) &&
+            service.migrations.separateTaskDef !== undefined) {
+            validateSeparateTaskDef(service.name, service.migrations.separateTaskDef);
+        }
+    }
+    if (props.cluster?.directAccess === true) {
+        const hasEc2Service = props.services.some((s) => s.capacityProvider === "EC2");
+        if (!hasEc2Service) {
+            throw new Error("cluster.directAccess: true requires at least one service with capacityProvider: 'EC2'. " +
+                "directAccess opens host-network ports on EC2 instances and has no effect on Fargate services.");
+        }
+        if (props.cluster.securityGroup !== undefined) {
+            throw new Error("cluster.directAccess: true cannot be combined with a caller-supplied cluster.securityGroup. " +
+                "directAccess adds 0.0.0.0/0 ingress rules to the ASG security group; routing those rules onto an " +
+                "externally-owned security group couples this construct's permissions onto a SG whose lifecycle it " +
+                "does not own. Either omit cluster.securityGroup (a Fjall-owned SG will be created) or set directAccess: false.");
+        }
+    }
+}
+const DEFAULT_MIGRATE_CONTAINER_NAME = "migrate";
+function lifecycleStageForHookMode(mode) {
+    switch (mode) {
+        case "lifecycle-hook":
+            return DeploymentLifecycleStage.PRE_SCALE_UP;
+        case "post-deploy":
+            return DeploymentLifecycleStage.POST_SCALE_UP;
+        default: {
+            const _exhaustive = mode;
+            throw new Error(`Unsupported hook migration mode: ${String(_exhaustive)}`);
+        }
+    }
+}
+/**
+ * Expand a service's `migrations` sugar into a synthetic init container plus
+ * auto-injected `dependsOn` entries on every other container.
+ *
+ * - Synthesises a non-essential container that runs the migration command and exits.
+ * - Inherits image / environment / secrets / secretsImport from the primary container
+ *   (first container with a port, or first container if none have a port).
+ * - Auto-wires every other container to wait on the migrate container's `SUCCESS`,
+ *   skipping containers that already declare the dependency to keep user overrides intact.
+ * - Throws on name collision when a user-defined container shares the migrate name.
+ *
+ * When `migrations.mode` is a lambda-hook variant (`"lifecycle-hook"` /
+ * `"post-deploy"`), this helper is a no-op: the task
+ * definition stays unmodified and the migration is run by a deployment lifecycle
+ * hook synthesised separately at the pattern layer.
+ *
+ * @internal Exported for testing only
+ */
+export function expandMigrationsSugar(service, userContainers) {
+    const migrations = service.migrations;
+    if (!migrations) {
+        return userContainers ?? [];
+    }
+    if (isHookMigrations(migrations)) {
+        return userContainers ?? [];
+    }
+    const migrateName = migrations.name ?? DEFAULT_MIGRATE_CONTAINER_NAME;
+    const containers = userContainers ?? [];
+    for (const c of containers) {
+        if (c.name === migrateName) {
+            throw new Error(`Service '${service.name}': container '${migrateName}' collides with the synthetic ` +
+                `migrate container created by 'migrations'. Set 'migrations.name' to a different value.`);
+        }
+    }
+    const primary = containers.find((c) => c.port !== undefined) ?? containers[0];
+    const migrateContainer = {
+        name: migrateName,
+        essential: false,
+        command: migrations.command,
+        image: migrations.image ?? primary?.image,
+        environment: migrations.environment ?? primary?.environment,
+        secrets: migrations.secrets ?? primary?.secrets,
+        secretsImport: migrations.secretsImport ?? primary?.secretsImport
+    };
+    const wired = containers.map((c) => {
+        const existing = c.dependsOn ?? [];
+        const alreadyDepends = existing.some((d) => d.container === migrateName);
+        if (alreadyDepends)
+            return c;
+        return {
+            ...c,
+            dependsOn: [
+                ...existing,
+                { container: migrateName, condition: "SUCCESS" }
+            ]
+        };
+    });
+    return [migrateContainer, ...wired];
+}
+/**
+ * Resolve the relational database carrying `migrations:` from a service's
+ * `connections` graph. Returns `undefined` when no connected database declares
+ * migrations. Throws when two or more do — the conflict names both databases
+ * so the author can pick a winner via service split or `schemaGate: false`.
+ *
+ * The author-explicit-wins arbitration for the env value itself lives in
+ * `buildContainerConfigs` — this helper only chooses the database.
+ */
+function resolveMigrationDatabaseForService(service) {
+    const connections = service.connections;
+    if (connections === undefined || connections.length === 0)
+        return undefined;
+    const matches = [];
+    for (const spec of connections) {
+        const resource = isConnectionConfig(spec) ? spec.resource : spec;
+        if (!isDatabase(resource))
+            continue;
+        if (!isRelationalDatabase(resource))
+            continue;
+        if (resource.getMigrationsConfig() !== undefined)
+            matches.push(resource);
+    }
+    if (matches.length === 0)
+        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 ` +
+            `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 ` +
+            `set \`schemaGate: false\` and inject the env manually.`);
+    }
+    return matches[0];
+}
+function getResourceLabel(resource) {
+    if (resource !== null &&
+        typeof resource === "object" &&
+        "node" in resource &&
+        resource.node !== null &&
+        typeof resource.node === "object" &&
+        "id" in resource.node &&
+        typeof resource.node.id === "string") {
+        return resource.node.id;
+    }
+    return resource?.constructor?.name ?? "<unknown>";
+}
+function isSecurityGroupPeer(peer) {
+    return typeof peer.addIngressRule === "function";
+}
+/**
+ * Walks a service's `connections:` array, dispatches through
+ * `isMigrationContributor`, and accumulates a single merged
+ * `MigrationContributions` describing what the migration task should inherit.
+ *
+ * Author-explicit-wins is enforced separately by the consumer
+ * (`mergeContributionsIntoMigrations` / `mergeContributionsIntoSeparateTaskDef`
+ * below). Here we ONLY arbitrate between contributors themselves: if two
+ * contributors disagree on an env key or `secretsImport` entry (two databases
+ * each contributing `DATABASE_HOST` with different values, or two ClickHouse
+ * instances each contributing `SCHEMA_ADMIN_PASSWORD` from different secrets),
+ * synth throws naming both resources so the author resolves via
+ * `migrations.environment.<key>` / `migrations.secretsImport.<key>` or by
+ * splitting the service. `taskRolePolicies` and `egress` are additive — no
+ * conflict resolution needed. Two-DB conflicts on the schema-version gate
+ * already throw upstream in `resolveMigrationDatabaseForService`.
+ */
+function collectMigrationContributions(service) {
+    const merged = {
+        environment: {},
+        secretsImport: {},
+        taskRolePolicies: [],
+        egress: []
+    };
+    const envOrigin = new Map();
+    const secretOrigin = new Map();
+    const connections = service.connections;
+    if (connections === undefined || connections.length === 0)
+        return merged;
+    for (const spec of connections) {
+        const resource = isConnectionConfig(spec) ? spec.resource : spec;
+        if (!isMigrationContributor(resource))
+            continue;
+        const contribution = resource.getMigrationContributions();
+        if (contribution === undefined)
+            continue;
+        const label = getResourceLabel(resource);
+        if (contribution.environment !== undefined) {
+            for (const [key, value] of Object.entries(contribution.environment)) {
+                const prior = envOrigin.get(key);
+                if (prior !== undefined && merged.environment[key] !== value) {
+                    throw new Error(`Service '${service.name}': contributors '${prior}' and '${label}' ` +
+                        `both contribute migration env '${key}' with conflicting values ` +
+                        `('${merged.environment[key]}' vs '${value}'). Resolve by setting ` +
+                        `migrations.environment.${key} explicitly on the service.`);
+                }
+                merged.environment[key] = value;
+                envOrigin.set(key, prior ?? label);
+            }
+        }
+        if (contribution.secretsImport !== undefined) {
+            for (const [key, value] of Object.entries(contribution.secretsImport)) {
+                const prior = secretOrigin.get(key);
+                if (prior !== undefined &&
+                    merged.secretsImport[key]?.name !== value.name) {
+                    throw new Error(`Service '${service.name}': contributors '${prior}' and '${label}' ` +
+                        `both contribute migration secretsImport '${key}' with conflicting ` +
+                        `values (secret '${merged.secretsImport[key]?.name ?? ""}' vs ` +
+                        `'${value.name}'). Resolve by setting migrations.secretsImport.${key} ` +
+                        `explicitly on the service.`);
+                }
+                merged.secretsImport[key] = value;
+                secretOrigin.set(key, prior ?? label);
+            }
+        }
+        if (contribution.taskRolePolicies !== undefined) {
+            merged.taskRolePolicies.push(...contribution.taskRolePolicies);
+        }
+        if (contribution.egress !== undefined) {
+            merged.egress.push(...contribution.egress);
+        }
     }
+    return merged;
+}
+/**
+ * Merge contributor-supplied env/secrets into the author's explicit
+ * `migrations:` block. Author-explicit wins on key collisions with a synth
+ * warning so the author can audit what was overridden.
+ */
+function mergeContributionsIntoMigrations(migrations, contributions, scope, serviceName) {
+    const contributedEnv = contributions.environment ?? {};
+    const contributedSecrets = contributions.secretsImport ?? {};
+    const authoredEnv = migrations.environment ?? {};
+    const authoredSecrets = migrations.secretsImport ?? {};
+    const mergedEnv = { ...contributedEnv };
+    for (const [key, value] of Object.entries(authoredEnv)) {
+        if (contributedEnv[key] !== undefined && contributedEnv[key] !== value) {
+            Annotations.of(scope).addWarning(`Service '${serviceName}': author-set migrations.environment.${key}` +
+                `='${value}' overrides contributor value ` +
+                `('${contributedEnv[key]}').`);
+        }
+        mergedEnv[key] = value;
+    }
+    const mergedSecrets = { ...contributedSecrets };
+    for (const [key, value] of Object.entries(authoredSecrets)) {
+        if (contributedSecrets[key] !== undefined &&
+            contributedSecrets[key]?.name !== value.name) {
+            Annotations.of(scope).addWarning(`Service '${serviceName}': author-set migrations.secretsImport.${key} ` +
+                `(secret '${value.name}') overrides contributor secret ` +
+                `('${contributedSecrets[key]?.name ?? ""}').`);
+        }
+        mergedSecrets[key] = value;
+    }
+    return {
+        ...migrations,
+        ...(Object.keys(mergedEnv).length > 0 && { environment: mergedEnv }),
+        ...(Object.keys(mergedSecrets).length > 0 && {
+            secretsImport: mergedSecrets
+        })
+    };
+}
+/**
+ * Merge contributor-supplied IAM policies and egress entries into the author's
+ * `separateTaskDef` block. Both fields are additive — contributor entries are
+ * appended to the author's list.
+ */
+function mergeContributionsIntoSeparateTaskDef(separateTaskDef, contributions) {
+    const contributedPolicies = contributions.taskRolePolicies ?? [];
+    const contributedEgress = contributions.egress ?? [];
+    const mergedPolicies = [
+        ...contributedPolicies,
+        ...(separateTaskDef.taskRolePolicies ?? [])
+    ];
+    const mergedEgress = [
+        ...contributedEgress,
+        ...(separateTaskDef.egressTo ?? [])
+    ];
+    return {
+        ...separateTaskDef,
+        ...(mergedPolicies.length > 0 && { taskRolePolicies: mergedPolicies }),
+        ...(mergedEgress.length > 0 && { egressTo: mergedEgress })
+    };
 }
 /**
  * Build container configurations for an ECS service.
  * Converts user-facing EcsContainerConfig to internal EcsClusterProps format.
+ *
+ * @param service       Service config from EcsComputeProps.
+ * @param schemaVersionEnv Pre-resolved `{ EXPECTED_SCHEMA_VERSION: <ver> }`
+ *                      from a connected database's `migrations:` config, or
+ *                      `undefined` when the service has no migrated DB or
+ *                      opted out via `schemaGate: false`.
+ * @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.
  * @internal Exported for testing only
  */
-export function buildContainerConfigs(service) {
-    if (service.containers && service.containers.length > 0) {
-        return service.containers.map((c, index) => ({
-            name: c.name || `${service.name}Container${index > 0 ? index : ""}`,
-            image: c.image,
-            port: c.port,
-            environment: c.environment,
-            secrets: c.secrets,
-            secretsImport: c.secretsImport,
-            command: c.command,
-            entryPoint: c.entryPoint,
-            essential: c.essential,
-            healthCheck: c.healthCheck
-        }));
+export function buildContainerConfigs(service, schemaVersionEnv, annotationsScope) {
+    const userContainers = service.containers && service.containers.length > 0
+        ? service.containers
+        : undefined;
+    const expanded = service.migrations
+        ? expandMigrationsSugar(service, userContainers)
+        : userContainers;
+    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 ?? {}) };
+        for (const [key, value] of Object.entries(schemaVersionEnv)) {
+            if (merged[key] === undefined)
+                merged[key] = value;
+        }
+        return merged;
+    };
+    if (expanded) {
+        return expanded.map((c, index) => {
+            return {
+                name: c.name || `${service.name}Container${index > 0 ? index : ""}`,
+                image: c.image,
+                port: c.port,
+                environment: mergeSchemaEnv(c.environment),
+                secrets: c.secrets,
+                secretsImport: c.secretsImport,
+                command: c.command,
+                entryPoint: c.entryPoint,
+                essential: c.essential,
+                healthCheck: c.healthCheck,
+                dependsOn: c.dependsOn,
+                portMappings: c.portMappings,
+                volumes: c.volumes,
+                stopTimeout: c.stopTimeout
+            };
+        });
     }
-    // Default container (no port = worker)
-    return [{ name: `${service.name}Container` }];
+    const fallbackEnv = mergeSchemaEnv(undefined);
+    return [
+        {
+            name: `${service.name}Container`,
+            ...(fallbackEnv !== undefined && { environment: fallbackEnv })
+        }
+    ];
+}
+function resolveMigrationImage(svcConfig, migrations, inheritedImage) {
+    if (migrations.image !== undefined)
+        return migrations.image;
+    // Order dependency: inheritedImage carries the <ServiceName>ImageTag
+    // CfnParameter token; checked before raw svcConfig.image strings.
+    if (inheritedImage !== undefined)
+        return inheritedImage;
+    const primary = svcConfig.containers?.find((c) => c.port !== undefined) ??
+        svcConfig.containers?.[0];
+    const containerImage = primary?.image ?? svcConfig.image;
+    if (containerImage !== undefined && typeof containerImage !== "string") {
+        throw new Error(`Service '${svcConfig.name}': migrations.separateTaskDef requires a string image URI ` +
+            `(got CDK Repository). Pass migrations.image as a string.`);
+    }
+    if (containerImage === undefined) {
+        throw new Error(`Service '${svcConfig.name}': migrations.separateTaskDef requires a resolvable image — ` +
+            `set migrations.image, service.image, or a container.image (string URI).`);
+    }
+    return containerImage;
 }
 /**
  * Resolve scaling configuration from service props.
@@ -143,12 +552,26 @@ export class EcsCompute extends Construct {
     computeType = "ecs";
     connections;
     ecsCluster;
+    clusterId;
+    appName;
+    migrationTaskDefinitions = new Map();
     constructor(scope, id, props) {
         super(scope, id);
-        // Transform EcsServiceConfig[] to EcsServiceProps[] for EcsCluster
+        validateEcsProps(props);
+        this.clusterId = id;
+        this.appName = props.appName;
         const services = props.services.map((service) => {
-            const containers = buildContainerConfigs(service);
+            const schemaVersionEnv = this.resolveSchemaVersionEnv(service);
+            const containers = buildContainerConfigs(service, schemaVersionEnv, this);
             const { scalingType, minCapacity, maxCapacity } = resolveScalingConfig(service.scaling);
+            const cloudMapService = service.serviceDiscovery !== undefined
+                ? App.getInstance().registerService({
+                    name: service.serviceDiscovery.name,
+                    ...(service.serviceDiscovery.dnsRecordType !== undefined && {
+                        dnsRecordType: service.serviceDiscovery.dnsRecordType
+                    })
+                })
+                : undefined;
             return {
                 name: service.name,
                 image: service.image,
@@ -163,33 +586,40 @@ export class EcsCompute extends Construct {
                 taskRoleInlinePolicies: service.taskRoleInlinePolicies,
                 taskRoleManagedPolicies: service.taskRoleManagedPolicies,
                 connections: service.connections,
+                remoteConnections: service.remoteConnections,
                 capacityProvider: service.capacityProvider,
                 ec2Config: service.ec2Config,
                 ssmSecretsPath: service.ssmSecretsPath,
-                dockerTarget: service.dockerTarget,
-                alarms: service.alarms
+                docker: service.docker,
+                alarms: service.alarms,
+                circuitBreaker: service.circuitBreaker,
+                ...(service.deployment !== undefined && {
+                    deployment: service.deployment
+                }),
+                ...(cloudMapService !== undefined && { cloudMapService }),
+                ...(service.serviceDiscovery?.dnsRecordType !== undefined && {
+                    cloudMapDnsRecordType: service.serviceDiscovery.dnsRecordType
+                }),
+                ...(service.networkMode !== undefined && {
+                    networkMode: service.networkMode
+                }),
+                ...(service.securityGroups !== undefined && {
+                    securityGroups: service.securityGroups
+                })
             };
         });
-        // Build cluster config
         const cluster = props.cluster
             ? {
                 domain: props.cluster.domain,
                 loadBalancer: props.cluster.loadBalancer,
                 directAccess: props.cluster.directAccess,
-                domainConfig: props.cluster.domainConfig
+                domainConfig: props.cluster.domainConfig,
+                ...(props.cluster.securityGroup !== undefined && {
+                    securityGroup: props.cluster.securityGroup
+                })
             }
             : undefined;
-        // Resolve alertsTopic: accept ITopic directly or string (ARN or "import:ExportName")
-        let resolvedAlertsTopic;
-        if (typeof props.alertsTopic === "string") {
-            const arn = props.alertsTopic.startsWith("import:")
-                ? Fn.importValue(props.alertsTopic.slice("import:".length))
-                : props.alertsTopic;
-            resolvedAlertsTopic = Topic.fromTopicArn(this, "AlertsTopic", arn);
-        }
-        else {
-            resolvedAlertsTopic = props.alertsTopic;
-        }
+        const resolvedAlertsTopic = resolveAlertsTopic(this, `${id}AlertsTopic`, props.alertsTopic);
         const ecsProps = {
             clusterName: id,
             appName: props.appName,
@@ -200,8 +630,381 @@ export class EcsCompute extends Construct {
             alertsTopic: resolvedAlertsTopic,
             applicationId: props.applicationId
         };
-        this.ecsCluster = new EcsCluster(scope, `${id}Ecs`, ecsProps);
+        this.ecsCluster = new EcsCluster(this, `${id}Ecs`, ecsProps);
         this.connections = this.ecsCluster.connections;
+        this.wireLifecycleHookMigrations(props.services);
+        this.materialiseScheduledTasks(id, props);
+    }
+    /**
+     * Walks a service's `connections:` for a relational database carrying a
+     * `migrations:` config. Returns the schema-version gate env entries to
+     * thread into the service's containers, or `undefined` when the service is
+     * not gated.
+     *
+     * - `schemaGate: false` → returns `undefined` (auditable opt-out)
+     * - No migrated DB in connections → returns `undefined`
+     * - Exactly one migrated DB → returns `{ EXPECTED_SCHEMA_VERSION, EXPECTED_SCHEMA_VERSION_TOOL }`
+     * - Two or more migrated DBs → throws via `resolveMigrationDatabaseForService`
+     *
+     * Both envs always emit together. The tool sibling lets the runtime gate
+     * dispatch to the matching resolver (or refuse on unknown tool) instead of
+     * hardcoding one.
+     */
+    resolveSchemaVersionEnv(service) {
+        if (service.schemaGate === false)
+            return undefined;
+        const db = resolveMigrationDatabaseForService(service);
+        if (db === undefined)
+            return undefined;
+        const version = db.getExpectedSchemaVersion();
+        if (version === undefined)
+            return undefined;
+        const config = db.getMigrationsConfig();
+        if (config === undefined) {
+            throw new Error(`Service '${service.name}': schema-version-gate produced a version ` +
+                `but the connected database returned no migrations config — these ` +
+                `must move together.`);
+        }
+        return {
+            [EXPECTED_SCHEMA_VERSION_ENV]: version,
+            [EXPECTED_SCHEMA_VERSION_TOOL_ENV]: config.tool
+        };
+    }
+    materialiseScheduledTasks(id, props) {
+        const scheduledTasks = props.cluster?.scheduledTasks;
+        if (!scheduledTasks || scheduledTasks.length === 0)
+            return;
+        const app = App.getInstance();
+        for (const entry of scheduledTasks) {
+            const taskDef = this.buildScheduledTaskDefinition(id, entry);
+            this.ecsCluster.registerScheduledTaskDefinition(entry.name, taskDef);
+            app.addSchedule(`${id}${toPascalCase(entry.name)}Schedule`, {
+                schedule: entry.schedule,
+                target: {
+                    ecs: this,
+                    serviceName: entry.name,
+                    taskCount: 1
+                },
+                stackPlacement: "compute"
+            });
+        }
+    }
+    buildScheduledTaskDefinition(id, entry) {
+        const taskDef = createScheduledTaskDefinition(this, `${id}${toPascalCase(entry.name)}TaskDefinition`, {
+            family: `${id}-${entry.name}`,
+            ...(entry.networkMode !== undefined && {
+                networkMode: entry.networkMode
+            })
+        });
+        if (entry.volumes) {
+            for (const volume of entry.volumes) {
+                taskDef.addVolume({
+                    name: volume.name,
+                    ...(volume.hostSourcePath !== undefined && {
+                        host: { sourcePath: volume.hostSourcePath }
+                    })
+                });
+            }
+        }
+        const logging = new AwsLogDriver({
+            streamPrefix: `/ecs-scheduled/${id}/${entry.name}`,
+            ...(entry.logGroup !== undefined && { logGroup: entry.logGroup }),
+            ...(entry.logGroup === undefined &&
+                entry.logRetention !== undefined && {
+                logRetention: entry.logRetention
+            })
+        });
+        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 }),
+            logging
+        });
+        if (entry.volumes) {
+            for (const volume of entry.volumes) {
+                container.addMountPoints({
+                    sourceVolume: volume.name,
+                    containerPath: volume.mountPath,
+                    readOnly: volume.readOnly ?? false
+                });
+            }
+        }
+        return taskDef;
+    }
+    /**
+     * For each service whose `migrations.mode` is a lambda-hook variant
+     * (`"lifecycle-hook"` for PRE_SCALE_UP, `"post-deploy"` for POST_SCALE_UP),
+     * synthesise the Lambda + IAM role + log group that backs the deployment
+     * lifecycle hook. The init-container path is unaffected — services without
+     * `mode` (or with `mode: "init-container"`) still get the synthetic
+     * migrate container injected by `expandMigrationsSugar`.
+     */
+    wireLifecycleHookMigrations(services) {
+        for (const svcConfig of services) {
+            const migrations = svcConfig.migrations;
+            if (!migrations || !isHookMigrations(migrations))
+                continue;
+            const modeLabel = migrations.mode;
+            if (svcConfig.capacityProvider === "EC2") {
+                throw new Error(`Service '${svcConfig.name}': migrations.mode === "${modeLabel}" requires FARGATE or FARGATE_SPOT capacity (got "EC2"). ` +
+                    `Use migrations.mode === "init-container" (the default) for EC2 services.`);
+            }
+            if (migrations.image !== undefined &&
+                typeof migrations.image !== "string") {
+                throw new Error(`Service '${svcConfig.name}': migrations.image must be a string in ${modeLabel} mode. ` +
+                    `CDK Repository constructs are not supported here — pass the image URI as a string.`);
+            }
+            const service = this.ecsCluster.getService(svcConfig.name);
+            if (!service) {
+                throw new Error(`Service '${svcConfig.name}' not found in cluster after synthesis — cannot attach lifecycle hook.`);
+            }
+            const taskDefinition = service.taskDefinition;
+            if (!taskDefinition.executionRole) {
+                throw new Error(`Service '${svcConfig.name}': task definition has no execution role — cannot grant iam:PassRole for the migrate Lambda.`);
+            }
+            const cluster = this.ecsCluster.getCluster();
+            const hasNat = vpcHasNatGateways(cluster.vpc);
+            const subnets = cluster.vpc.selectSubnets({
+                subnetType: hasNat ? SubnetType.PRIVATE_WITH_EGRESS : SubnetType.PUBLIC
+            });
+            const securityGroupIds = service.connections.securityGroups.map((sg) => sg.securityGroupId);
+            if (securityGroupIds.length === 0) {
+                throw new Error(`EcsCompute: service "${svcConfig.name}" has no security groups; lifecycle-hook migration RunTask requires at least one.`);
+            }
+            const contributions = collectMigrationContributions(svcConfig);
+            const effectiveMigrations = mergeContributionsIntoMigrations(migrations, contributions, this, svcConfig.name);
+            const effectiveSeparateTaskDef = migrations.separateTaskDef !== undefined
+                ? mergeContributionsIntoSeparateTaskDef(migrations.separateTaskDef, contributions)
+                : undefined;
+            const schemaVersionEnv = this.resolveSchemaVersionEnv(svcConfig);
+            const migrationTaskDef = effectiveSeparateTaskDef !== undefined
+                ? this.synthesiseMigrationTaskDef(svcConfig, effectiveMigrations, effectiveSeparateTaskDef, service, cluster.vpc, schemaVersionEnv)
+                : undefined;
+            const effectiveSecurityGroupIds = migrationTaskDef?.securityGroupIds ?? securityGroupIds;
+            new EcsLifecycleHookMigration(this, `${toPascalCase(svcConfig.name)}Migrate`, {
+                service,
+                clusterArn: cluster.clusterArn,
+                taskDefinitionArn: taskDefinition.taskDefinitionArn,
+                taskDefinitionFamily: taskDefinition.family,
+                taskExecutionRoleArn: taskDefinition.executionRole.roleArn,
+                taskRoleArn: taskDefinition.taskRole.roleArn,
+                command: effectiveMigrations.command,
+                containerName: effectiveMigrations.name ?? DEFAULT_MIGRATE_CONTAINER_NAME,
+                image: effectiveMigrations.image,
+                ...(effectiveMigrations.entryPoint !== undefined && {
+                    entryPoint: effectiveMigrations.entryPoint
+                }),
+                environment: effectiveMigrations.environment,
+                timeoutSeconds: effectiveMigrations.timeoutSeconds,
+                networkConfiguration: {
+                    subnetIds: subnets.subnetIds,
+                    securityGroupIds: effectiveSecurityGroupIds,
+                    assignPublicIp: !hasNat
+                },
+                ...(migrationTaskDef !== undefined && {
+                    migrationTaskDef: {
+                        definitionArn: migrationTaskDef.taskDefinitionArn,
+                        family: migrationTaskDef.family,
+                        taskRoleArn: migrationTaskDef.taskRoleArn,
+                        executionRoleArn: migrationTaskDef.executionRoleArn
+                    }
+                }),
+                lifecycleStage: lifecycleStageForHookMode(effectiveMigrations.mode)
+            });
+        }
+    }
+    /**
+     * Synthesise a dedicated migration task definition for a lifecycle-hook
+     * migration when `separateTaskDef` is set. Creates the migration's own
+     * execution + task roles, log group, security group (when `egressTo` is
+     * present, else reuses the service's SGs), and the Fargate task definition
+     * with the migration container baked in.
+     */
+    synthesiseMigrationTaskDef(svcConfig, migrations, separateTaskDef, service, vpc, schemaVersionEnv) {
+        const stack = Stack.of(this);
+        const idPrefix = `${toPascalCase(svcConfig.name)}Migrate`;
+        const containerName = migrations.name ?? DEFAULT_MIGRATE_CONTAINER_NAME;
+        const family = `${this.clusterId}-${svcConfig.name}-migrate`;
+        const inheritedImage = service.taskDefinition.defaultContainer?.imageName;
+        const image = resolveMigrationImage(svcConfig, migrations, inheritedImage);
+        const logGroup = new LogGroup(this, `${idPrefix}LogGroup`, {
+            retention: RetentionDays.ONE_MONTH
+        });
+        const executionRole = new Role(this, `${idPrefix}ExecutionRole`, {
+            assumedBy: new ServicePrincipal("ecs-tasks.amazonaws.com")
+        });
+        executionRole.addToPolicy(new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: [
+                "ecr:GetAuthorizationToken",
+                "ecr:BatchCheckLayerAvailability",
+                "ecr:GetDownloadUrlForLayer",
+                "ecr:BatchGetImage"
+            ],
+            resources: ["*"]
+        }));
+        logGroup.grantWrite(executionRole);
+        const taskRole = new Role(this, `${idPrefix}TaskRole`, {
+            assumedBy: new ServicePrincipal("ecs-tasks.amazonaws.com")
+        });
+        taskRole.addToPolicy(new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: [
+                "ssmmessages:CreateControlChannel",
+                "ssmmessages:CreateDataChannel",
+                "ssmmessages:OpenControlChannel",
+                "ssmmessages:OpenDataChannel"
+            ],
+            resources: ["*"]
+        }));
+        if (separateTaskDef.taskRolePolicies) {
+            for (const statement of separateTaskDef.taskRolePolicies) {
+                taskRole.addToPolicy(statement);
+            }
+        }
+        if (separateTaskDef.extraSecretReads) {
+            const stackHere = Stack.of(this);
+            const secretArns = separateTaskDef.extraSecretReads.map((entry) => entry.secretName.startsWith("arn:")
+                ? entry.secretName
+                : `arn:${stackHere.partition}:secretsmanager:${stackHere.region}:${stackHere.account}:secret:${entry.secretName}-*`);
+            taskRole.addToPolicy(new PolicyStatement({
+                effect: Effect.ALLOW,
+                actions: ["secretsmanager:GetSecretValue"],
+                resources: secretArns
+            }));
+        }
+        const taskDefinition = createMigrationTaskDefinition(this, `${idPrefix}TaskDefinition`, {
+            family,
+            cpu: separateTaskDef.cpu,
+            memoryLimitMiB: separateTaskDef.memoryLimitMiB,
+            executionRole,
+            taskRole
+        });
+        const { secretsResolved, secretArns, ssmPath } = this.resolveMigrationSecrets(svcConfig, migrations, idPrefix);
+        const authoredEnvironment = migrations.environment ?? {};
+        const containerEnvironment = {
+            ...authoredEnvironment
+        };
+        if (schemaVersionEnv !== undefined) {
+            for (const [key, value] of Object.entries(schemaVersionEnv)) {
+                if (containerEnvironment[key] === undefined) {
+                    containerEnvironment[key] = value;
+                }
+            }
+        }
+        taskDefinition.addContainer(`${idPrefix}Container`, {
+            containerName,
+            image: ContainerImage.fromRegistry(image),
+            command: migrations.command,
+            ...(migrations.entryPoint !== undefined && {
+                entryPoint: migrations.entryPoint
+            }),
+            environment: containerEnvironment,
+            secrets: secretsResolved,
+            logging: new AwsLogDriver({
+                streamPrefix: `/ecs-migrate/${svcConfig.name}`,
+                logGroup
+            })
+        });
+        if (secretArns.length > 0) {
+            executionRole.addToPolicy(new PolicyStatement({
+                effect: Effect.ALLOW,
+                actions: [
+                    "secretsmanager:GetSecretValue",
+                    "secretsmanager:DescribeSecret"
+                ],
+                resources: secretArns
+            }));
+        }
+        if (ssmPath !== undefined) {
+            executionRole.addToPolicy(new PolicyStatement({
+                effect: Effect.ALLOW,
+                actions: ["ssm:GetParameters", "ssm:GetParameter"],
+                resources: [
+                    `arn:${stack.partition}:ssm:${stack.region}:${stack.account}:parameter${ssmPath}/*`
+                ]
+            }));
+        }
+        if (secretArns.length > 0 || ssmPath !== undefined) {
+            executionRole.addToPolicy(new PolicyStatement({
+                effect: Effect.ALLOW,
+                actions: ["kms:Decrypt"],
+                resources: ["*"],
+                conditions: {
+                    StringEquals: {
+                        "kms:ViaService": [
+                            `ssm.${stack.region}.amazonaws.com`,
+                            `secretsmanager.${stack.region}.amazonaws.com`
+                        ]
+                    }
+                }
+            }));
+        }
+        let securityGroupIds;
+        if (separateTaskDef.egressTo !== undefined &&
+            separateTaskDef.egressTo.length > 0) {
+            const migrationSg = new SecurityGroup(this, `${idPrefix}SecurityGroup`, {
+                vpc,
+                description: `Migration SG for ${svcConfig.name}`,
+                allowAllOutbound: false
+            });
+            for (const [i, egress] of separateTaskDef.egressTo.entries()) {
+                migrationSg.addEgressRule(egress.peer, egress.port, egress.description);
+                if (isSecurityGroupPeer(egress.peer)) {
+                    // Cross-stack: addIngressRule on the peer directly cycles
+                    // (peer stack would back-ref migrationSg). Import locally.
+                    const localPeer = SecurityGroup.fromSecurityGroupId(this, `${idPrefix}MigratePeer${i}`, egress.peer.securityGroupId, { mutable: true });
+                    localPeer.addIngressRule(migrationSg, egress.port, egress.description);
+                }
+            }
+            // Fargate agent pre-container 443 fetches; ECR API needs NAT egress.
+            migrationSg.addEgressRule(Peer.anyIpv4(), Port.tcp(443), "Fargate agent HTTPS for ECR / secrets / logs");
+            securityGroupIds = [migrationSg.securityGroupId];
+        }
+        else {
+            securityGroupIds = service.connections.securityGroups.map((sg) => sg.securityGroupId);
+        }
+        this.migrationTaskDefinitions.set(svcConfig.name, taskDefinition);
+        return {
+            taskDefinitionArn: taskDefinition.taskDefinitionArn,
+            family: taskDefinition.family,
+            taskRoleArn: taskRole.roleArn,
+            executionRoleArn: executionRole.roleArn,
+            securityGroupIds
+        };
+    }
+    resolveMigrationSecrets(svcConfig, migrations, idPrefix) {
+        const stack = Stack.of(this);
+        const secretsResolved = {};
+        const secretArns = [];
+        if (migrations.secretsImport) {
+            for (const [key, secretImport] of Object.entries(migrations.secretsImport)) {
+                const secret = Secret.fromSecretNameV2(this, `${idPrefix}${key}Secret`, secretImport.name);
+                secretsResolved[key] = EcsSecret.fromSecretsManager(secret, secretImport.field);
+                secretArns.push(`arn:${stack.partition}:secretsmanager:${stack.region}:${stack.account}:secret:${secretImport.name}-*`);
+            }
+        }
+        let ssmPath;
+        if (migrations.secrets && migrations.secrets.length > 0) {
+            if (svcConfig.ssmSecretsPath !== undefined) {
+                ssmPath = svcConfig.ssmSecretsPath;
+            }
+            else {
+                if (this.appName === undefined || this.appName === "") {
+                    throw new Error(`Service '${svcConfig.name}' declares migration secrets but no ssmSecretsPath ` +
+                        `is set and EcsComputeProps.appName is missing — set one to enable ` +
+                        `SSM path derivation (/<appName>/<clusterName>/<serviceName>).`);
+                }
+                ssmPath = `/${this.appName}/${this.clusterId}/${svcConfig.name}`;
+            }
+            for (const secretName of migrations.secrets) {
+                const param = StringParameter.fromSecureStringParameterAttributes(this, `${idPrefix}${secretName}SsmParam`, { parameterName: `${ssmPath}/${secretName}` });
+                secretsResolved[secretName] = EcsSecret.fromSsmParameter(param);
+            }
+        }
+        return { secretsResolved, secretArns, ssmPath };
     }
     /** Get the ECS cluster. */
     getCluster() {
@@ -220,14 +1023,25 @@ export class EcsCompute extends Construct {
         const servicesMap = this.ecsCluster.getServices();
         return Array.from(servicesMap.values());
     }
+    getTaskDefinition(serviceName) {
+        return this.ecsCluster.getTaskDefinition(serviceName);
+    }
+    /**
+     * Get the migration task definition for a service. Returns `undefined` when
+     * the service has no `migrations: { mode: "lifecycle-hook", separateTaskDef }`
+     * configured — escape hatch for callers that need to attach grants (e.g.
+     * `bucket.grantReadWrite(td.taskRole)`) to the migration task role.
+     */
+    getMigrationTaskDefinition(serviceName) {
+        return this.migrationTaskDefinitions.get(serviceName);
+    }
     /** Get the security group for the cluster. */
     getSecurityGroup() {
-        // Return the first security group from connections
-        const securityGroups = this.connections.securityGroups;
-        if (securityGroups.length === 0) {
+        const sg = this.connections.securityGroups[0];
+        if (!sg) {
             throw new Error("No security groups found for ECS cluster");
         }
-        return securityGroups[0];
+        return sg;
     }
     /**
      * Get the ALB listener if this is an ECS compute with ALB.
@@ -235,6 +1049,9 @@ export class EcsCompute extends Construct {
     getListener() {
         return this.ecsCluster.getListener();
     }
+    getPrimaryListenerPort() {
+        return this.getListener()?.port;
+    }
     /**
      * Get the underlying ECS cluster construct.
      */
@@ -253,4 +1070,21 @@ export class EcsCompute extends Construct {
             resourceArns: ["*"]
         });
     }
+    /**
+     * Get the EC2 instance role for the cluster's underlying ASG. EC2-mode
+     * clusters return the ASG instance role; Fargate-only clusters return
+     * `undefined`. Use to attach S3 grants etc. that must reach the host
+     * process (D10 — single accessor; no separate `getAutoScalingGroup()`).
+     */
+    getInstanceRole() {
+        return this.ecsCluster.getInstanceRole();
+    }
+    /**
+     * Get the underlying ASG's `autoScalingGroupName` token. String-only —
+     * D10 forbids exposing the ASG construct itself. Used by alarm helpers
+     * that need a CloudWatch dimension value.
+     */
+    getAutoScalingGroupName() {
+        return this.ecsCluster.getAutoScalingGroupName();
+    }
 }