@fjall/components-infrastructure 2.34.0 → 3.1.0

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

@@ -1,310 +1,12 @@
-import { Stack, Tags } from "aws-cdk-lib";
-import { CompositePrincipal, ServicePrincipal, PolicyDocument, PolicyStatement } from "aws-cdk-lib/aws-iam";
-import { FjallLogger } from "../../utils/validationLogger.js";
-import { InstanceClass, InstanceSize, InstanceType, MachineImage, MultipartBody, MultipartUserData, SubnetType, UserData } from "aws-cdk-lib/aws-ec2";
-import { safeEbs } from "../../resources/aws/compute/blockDeviceVolume.js";
-import { Source } from "aws-cdk-lib/aws-s3-deployment";
-import { Vpc } from "../../resources/aws/networking/vpc.js";
-import { Policy, Role } from "../../resources/aws/iam/index.js";
-import { BucketDeployment, S3Bucket } from "../../resources/aws/storage/index.js";
-import { SecureStringParameter } from "../../resources/aws/secrets/index.js";
-import { Ec2Instance } from "../../resources/aws/compute/ec2.js";
-import { SamApplication } from "../../resources/aws/compute/samApplication.js";
-import { applyCostAllocationTags } from "../../utils/costAllocationTags.js";
-export var AgentRelease;
-(function (AgentRelease) {
-    AgentRelease["STABLE"] = "stable";
-    AgentRelease["BETA"] = "beta";
-    AgentRelease["EDGE"] = "edge";
-})(AgentRelease || (AgentRelease = {}));
-export const BuildkiteDefaultProps = {
-    // Buildkite Agent Configuration
-    elasticStackVersion: "v6.30.0",
-    keyName: "",
-    buildkiteAgentRelease: AgentRelease.STABLE,
-    buildkiteAgentTags: "",
-    buildkiteAgentTimestampLines: false,
-    buildkiteAgentExperiments: "",
-    buildkiteAgentScalerVersion: "1.8.0",
-    logRetentionDays: 1,
-    buildkiteAgentTracingBackend: "",
-    buildkiteAgentCancelGracePeriod: 60,
-    buildkiteTerminateInstanceAfterJob: false,
-    buildkiteAdditionalSudoPermissions: "",
-    buildkiteQueue: "default",
-    agentsPerInstance: 1,
-    bootstrapScriptUrl: "",
-    agentEnvFileUrl: "",
-    authorizedUsersUrl: "",
-    // Infrastructure
-    agentInstanceType: InstanceType.of(InstanceClass.M5, InstanceSize.LARGE),
-    agentMinInstances: 0,
-    agentMaxInstances: 10,
-    agentVolumeSize: 250,
-    scalerEventSchedulePeriod: "1 minute",
-    scalerMinPollInterval: "10s",
-    spotCapacityPercentage: 75,
-    scaleOutFactor: "1.0",
-    scaleInIdlePeriod: 600,
-    scaleOutWaitingForJobs: false,
-    ecrAccessPolicy: "",
-    dockerNetworkingProtocol: "ipv4",
-    enableSecretsPlugin: true,
-    enableEcrPlugin: true,
-    enableDockerLoginPlugin: true,
-    enableDockerUserNamespaceRemap: true,
-    enableDockerExperimental: false,
-    enableInstanceStorage: false,
-    mountTmpfsAtTmp: true,
-    buildkiteAgentEnableGitMirrors: false,
-    pipelineSigningKMSKey: "",
-    pipelineSigningVerificationFailureBehavior: "block",
-    // Tags
-    environment: "platform",
-    owner: "engineer"
-};
-export class Buildkite extends Stack {
-    constructor(scope, id, props) {
-        super(scope, id, props);
-        applyCostAllocationTags(this, {
-            service: "buildkite",
-            domain: "platform",
-            environment: props.environment || "platform",
-            owner: props.owner ?? "engineer"
-        });
-        const tags = { ...props.tags };
-        // VPC
-        const vpc = new Vpc(this, `${id}Vpc`, {
-            accountId: props.accountId,
-            subnetConfiguration: [
-                {
-                    name: `${id}`,
-                    subnetType: SubnetType.PUBLIC
-                }
-            ]
-        });
-        // Artifacts Bucket
-        const artifactBucket = new S3Bucket(this, `${id}ArtifactBucket`);
-        const managedSecretsBucket = new S3Bucket(this, `${id}ManagedSecretsBucket`);
-        const buildkitePrivateSshKey = process.env.BUILDKITE_PRIVATE_SSH_KEY;
-        const hasBuildkitePrivateSshKey = buildkitePrivateSshKey !== undefined && buildkitePrivateSshKey !== "";
-        if (hasBuildkitePrivateSshKey) {
-            // Synth-time secret bake: Source.data() inlines the env var into the
-            // CDK asset bundle uploaded to the bootstrap S3 staging bucket. The
-            // synth host MUST hold the secret in env, and the CDK staging bucket
-            // inherits the secret's blast radius. Treat as Buildkite-only opt-in.
-            new BucketDeployment(this, `${id}SshKeyDeployment`, {
-                sources: [Source.data("private_ssh_key", buildkitePrivateSshKey)],
-                destinationBucket: managedSecretsBucket
-            });
-        }
-        else {
-            FjallLogger.warn("'BUILDKITE_PRIVATE_SSH_KEY' environment variable not declared. Skipping upload of private SSH key.");
-        }
-        const buildkiteAgentToken = process.env.BUILDKITE_AGENT_TOKEN;
-        const hasBuildkiteAgentToken = buildkiteAgentToken !== undefined && buildkiteAgentToken !== "";
-        const agentToken = new SecureStringParameter(this, `${id}AgentToken`, {
-            name: `/buildkite/agentToken`,
-            aliasName: `buildkiteAgentToken`,
-            value: buildkiteAgentToken,
-            overwrite: hasBuildkiteAgentToken,
-            tags: tags,
-            accountId: this.account,
-            region: this.region
-        });
-        // Buildkite Agent Execution Role
-        const agentRole = new Role(this, `${id}AgentRole`, {
-            roleName: `${id}AgentRole`,
-            description: "Buildkite Agent IAM Role",
-            inlinePolicies: {
-                ["decryptBuildkiteAgentToken"]: new PolicyDocument({
-                    statements: [
-                        new PolicyStatement({
-                            actions: ["kms:Decrypt"],
-                            resources: [agentToken.cmk.key.keyArn]
-                        })
-                    ]
-                }),
-                ["readBuildkiteAgentToken"]: new PolicyDocument({
-                    statements: [
-                        new PolicyStatement({
-                            actions: ["ssm:GetParameter"],
-                            resources: [
-                                `arn:${this.partition}:ssm:${this.region}:${this.account}:parameter${agentToken.name}`
-                            ]
-                        })
-                    ]
-                }),
-                ["readManagedSecretsBucket"]: new PolicyDocument({
-                    statements: [
-                        new PolicyStatement({
-                            actions: ["s3:Get*", "s3:List*"],
-                            resources: [
-                                managedSecretsBucket.bucketArn,
-                                `${managedSecretsBucket.bucketArn}/*`
-                            ]
-                        })
-                    ]
-                }),
-                ["writeArtifactBucket"]: new PolicyDocument({
-                    statements: [
-                        new PolicyStatement({
-                            actions: [
-                                "s3:GetObject",
-                                "s3:GetObjectAcl",
-                                "s3:GetObjectVersion",
-                                "s3:GetObjectVersionAcl",
-                                "s3:ListBucket",
-                                "s3:PutObject",
-                                "s3:PutObjectAcl",
-                                "s3:PutObjectVersionAcl"
-                            ],
-                            resources: [
-                                artifactBucket.bucketArn,
-                                `${artifactBucket.bucketArn}/*`
-                            ]
-                        })
-                    ]
-                }),
-                ["describeInstance"]: new PolicyDocument({
-                    statements: [
-                        new PolicyStatement({
-                            actions: [
-                                "autoscaling:DescribeAutoScalingInstances",
-                                "cloudwatch:PutMetricData",
-                                "cloudformation:DescribeStackResource",
-                                "ec2:DescribeTags"
-                            ],
-                            resources: ["*"]
-                        })
-                    ]
-                }),
-                ["logging"]: new PolicyDocument({
-                    statements: [
-                        new PolicyStatement({
-                            actions: [
-                                "logs:CreateLogGroup",
-                                "logs:CreateLogStream",
-                                "logs:PutLogEvents",
-                                "logs:DescribeLogGroups",
-                                "logs:DescribeLogStreams"
-                            ],
-                            resources: ["*"]
-                        })
-                    ]
-                }),
-                ["ssm"]: new PolicyDocument({
-                    statements: [
-                        new PolicyStatement({
-                            actions: [
-                                "ssm:DescribeInstanceProperties",
-                                "ssm:ListAssociations",
-                                "ssm:PutInventory",
-                                "ssm:UpdateInstanceInformation",
-                                "ssmmessages:CreateControlChannel",
-                                "ssmmessages:CreateDataChannel",
-                                "ssmmessages:OpenControlChannel",
-                                "ssmmessages:OpenDataChannel",
-                                "ec2messages:AcknowledgeMessage",
-                                "ec2messages:DeleteMessage",
-                                "ec2messages:FailMessage",
-                                "ec2messages:GetEndpoint",
-                                "ec2messages:GetMessages",
-                                "ec2messages:SendReply"
-                            ],
-                            resources: ["*"]
-                        })
-                    ]
-                })
-            },
-            assumedBy: new CompositePrincipal(new ServicePrincipal("autoscaling.amazonaws.com"), new ServicePrincipal("ec2.amazonaws.com"))
-        });
-        // Buildkite Agent EC2 User Data
-        const multipartUserData = new MultipartUserData();
-        // Cloud Config
-        const cloudConfigUserData = UserData.forLinux({
-            shebang: "#cloud-config"
-        });
-        cloudConfigUserData.addCommands("cloud_final_modules:", "  - [scripts-user, always]");
-        multipartUserData.addPart(MultipartBody.fromUserData(cloudConfigUserData, "text/cloud-config; charset='us-ascii'"));
-        // Mount Storage
-        const mountStorageUserData = UserData.forLinux({
-            shebang: "#!/bin/bash -v"
-        });
-        mountStorageUserData.addCommands(`BUILDKITE_ENABLE_INSTANCE_STORAGE='${props.enableInstanceStorage}' \\`, `BUILDKITE_MOUNT_TMPFS_AT_TMP='${props.mountTmpfsAtTmp}' \\`, "/usr/local/bin/bk-mount-instance-storage.sh");
-        multipartUserData.addPart(MultipartBody.fromUserData(mountStorageUserData, "text/x-shellscript; charset='us-ascii'"));
-        // Configure Docker
-        const configureDockerUserData = UserData.forLinux({
-            shebang: "#!/bin/bash -v"
-        });
-        configureDockerUserData.addCommands(`DOCKER_USERNS_REMAP='${props.enableDockerUserNamespaceRemap}' \\`, `DOCKER_EXPERIMENTAL='${props.enableDockerExperimental}' \\`, `DOCKER_NETWORKING_PROTOCOL='${props.dockerNetworkingProtocol}' \\`, `BUILDKITE_ENABLE_INSTANCE_STORAGE='${props.enableInstanceStorage}' \\`, "/usr/local/bin/bk-configure-docker.sh");
-        multipartUserData.addPart(MultipartBody.fromUserData(configureDockerUserData, "text/x-shellscript; charset='us-ascii'"));
-        const installElasticStackUserData = UserData.forLinux({
-            shebang: "#!/bin/bash -v"
-        });
-        installElasticStackUserData.addCommands(`BUILDKITE_STACK_NAME='${id}' \\`, `BUILDKITE_STACK_VERSION='${props.elasticStackVersion}' \\`, `BUILDKITE_SCALE_IN_IDLE_PERIOD='${props.scaleInIdlePeriod}' \\`, `BUILDKITE_SECRETS_BUCKET='${managedSecretsBucket.bucketName}' \\`, `BUILDKITE_SECRETS_BUCKET_REGION='${props.env?.region}' \\`, `BUILDKITE_AGENT_TOKEN_PATH='${agentToken.name}' \\`, `BUILDKITE_AGENTS_PER_INSTANCE='${props.agentsPerInstance}' \\`, `BUILDKITE_AGENT_TAGS='${props.buildkiteAgentTags}' \\`, `BUILDKITE_AGENT_TIMESTAMP_LINES='${props.buildkiteAgentTimestampLines}' \\`, `BUILDKITE_AGENT_EXPERIMENTS='${props.buildkiteAgentExperiments}' \\`, `BUILDKITE_AGENT_TRACING_BACKEND='${props.buildkiteAgentTracingBackend}' \\`, `BUILDKITE_AGENT_RELEASE='${props.buildkiteAgentRelease}' \\`, `BUILDKITE_AGENT_CANCEL_GRACE_PERIOD='${props.buildkiteAgentCancelGracePeriod}' \\`, `BUILDKITE_AGENT_SIGNING_KMS_KEY='${props.pipelineSigningKMSKey}' \\`, `BUILDKITE_AGENT_SIGNING_FAILURE_BEHAVIOR='${props.pipelineSigningVerificationFailureBehavior}' \\`, `BUILDKITE_QUEUE='${props.buildkiteQueue}' \\`, `BUILDKITE_AGENT_ENABLE_GIT_MIRRORS='${props.buildkiteAgentEnableGitMirrors}' \\`, `BUILDKITE_ELASTIC_BOOTSTRAP_SCRIPT='${props.bootstrapScriptUrl}' \\`, `BUILDKITE_ENV_FILE_URL='${props.agentEnvFileUrl}' \\`, `BUILDKITE_ENABLE_INSTANCE_STORAGE='${props.enableInstanceStorage}' \\`, `BUILDKITE_AUTHORIZED_USERS_URL='${props.authorizedUsersUrl}' \\`, `BUILDKITE_ECR_POLICY='${props.ecrAccessPolicy}' \\`, `BUILDKITE_TERMINATE_INSTANCE_AFTER_JOB='${props.buildkiteTerminateInstanceAfterJob}' \\`, `BUILDKITE_ADDITIONAL_SUDO_PERMISSIONS='${props.buildkiteAdditionalSudoPermissions}' \\`, `AWS_DEFAULT_REGION='${props.env?.region}' \\`, `SECRETS_PLUGIN_ENABLED='${props.enableSecretsPlugin}' \\`, `ECR_PLUGIN_ENABLED='${props.enableEcrPlugin}' \\`, `DOCKER_LOGIN_PLUGIN_ENABLED='${props.enableDockerLoginPlugin}' \\`, `DOCKER_EXPERIMENTAL='${props.enableDockerExperimental}' \\`, `DOCKER_USERNS_REMAP='${props.enableDockerUserNamespaceRemap}' \\`, `AWS_REGION='${props.env?.region}' \\`, "/usr/local/bin/bk-install-elastic-stack.sh");
-        // Merge User Data
-        multipartUserData.addPart(MultipartBody.fromUserData(installElasticStackUserData, "text/x-shellscript; charset='us-ascii'"));
-        const ec2Instance = new Ec2Instance(this, `${id}Agent`, {
-            serviceName: `${id}Agent`,
-            vpc,
-            vpcSubnets: { subnetType: SubnetType.PUBLIC },
-            instanceType: props.agentInstanceType.toString(),
-            machineImage: MachineImage.lookup({
-                name: "buildkite-stack-linux-x86_64-*",
-                owners: ["172840064832"],
-                filters: {
-                    ["block-device-mapping.volume-type"]: ["gp3"]
-                }
-            }),
-            userData: multipartUserData,
-            role: agentRole,
-            blockDevices: [
-                {
-                    deviceName: "/dev/xvda",
-                    volume: safeEbs(props.agentVolumeSize)
-                }
-            ],
-            minCapacity: props.agentMinInstances,
-            maxCapacity: props.agentMaxInstances,
-            spotCapacityPercentage: props.spotCapacityPercentage
-        });
-        Tags.of(ec2Instance).add("Role", "buildkiteAgent");
-        Tags.of(ec2Instance).add("BuildkiteAgentRelease", props.buildkiteAgentRelease);
-        Tags.of(ec2Instance).add("BuildkiteQueue", props.buildkiteQueue);
-        const autoScalingGroup = ec2Instance.getAutoScalingGroup();
-        agentRole.attachInlinePolicy(new Policy(this, `${id}UpdateAutoScalingGroupPolicy`, {
-            statements: [
-                new PolicyStatement({
-                    actions: [
-                        "autoscaling:SetInstanceHealth",
-                        "autoscaling:TerminateInstanceInAutoScalingGroup"
-                    ],
-                    resources: [`${autoScalingGroup.autoScalingGroupArn}`]
-                })
-            ]
-        }));
-        new SamApplication(this, `${id}AgentScaler`, {
-            applicationId: "arn:aws:serverlessrepo:us-east-1:172840064832:applications/buildkite-agent-scaler",
-            semanticVersion: props.buildkiteAgentScalerVersion,
-            parameters: {
-                BuildkiteAgentTokenParameter: `${agentToken.name}`,
-                BuildkiteAgentTokenParameterStoreKMSKey: agentToken.cmk.key.keyId,
-                RolePermissionsBoundaryARN: "",
-                BuildkiteQueue: props.buildkiteQueue,
-                AgentsPerInstance: `${props.agentsPerInstance}`,
-                MinSize: `${props.agentMinInstances}`,
-                MaxSize: `${props.agentMaxInstances}`,
-                AgentAutoScaleGroup: autoScalingGroup.autoScalingGroupName,
-                ScaleOutFactor: props.scaleOutFactor,
-                ScaleOutForWaitingJobs: `${props.scaleOutWaitingForJobs}`,
-                EventSchedulePeriod: props.scalerEventSchedulePeriod,
-                MinPollInterval: props.scalerMinPollInterval,
-                LogRetentionDays: `${props.logRetentionDays}`
-            },
-            costAllocationService: "buildkite",
-            costAllocationDomain: "buildkite-agent-scaler"
-        });
-    }
-}
-export default Buildkite;
+/**
+ * Self-hosted Buildkite agent fleet — barrel for the `buildkite/` modules.
+ * The pre-2026-07 `Buildkite extends Stack` implementation is replaced by a
+ * Construct instantiated via `App.addBuildkite()`; design:
+ * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`.
+ */
+export { Buildkite, FJALL_ENV_HOOK_OBJECT_KEY, buildFjallApiKeyEnvHookScript } from "./buildkite/buildkite.js";
+export { BUILDKITE_AMI_OWNER_ACCOUNT_ID, BUILDKITE_CPU_ARCHITECTURES, BUILDKITE_STACK_PINS, resolvePinnedAmiId, resolveScalerSarApplicationArn } from "./buildkite/pins.js";
+export { BuildkitePropsSchema, validateBuildkiteProps } from "./buildkite/schema.js";
+export { BUILDKITE_AGENT_IAM_ACTION_ALLOWLIST, buildAgentRole } from "./buildkite/iam.js";
+export { BUILDKITE_DOCKER_PART_ENV_KEYS, BUILDKITE_MOUNT_PART_ENV_KEYS, BUILDKITE_USER_DATA_ENV_KEYS, buildBuildkiteDockerCommands, buildBuildkiteInstallCommands, buildBuildkiteMountCommands, buildBuildkiteUserData } from "./buildkite/userData.js";
+export { addBuildkiteAlarms } from "./buildkite/alarms.js";

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

@@ -1,23 +1,38 @@
-import { Fn } from "aws-cdk-lib";
+import { Fn, Token } from "aws-cdk-lib";
 import { Certificate } from "aws-cdk-lib/aws-certificatemanager";
 import { CloudFrontDistribution } from "../../resources/aws/cdn/index.js";
 import { isStorage } from "./storage.js";
 import { isCompute, isEcsCompute, isLambdaCompute } from "./compute.js";
-import { FjallLogger } from "../../utils/validationLogger.js";
 /**
- * Validates CDN props and logs warnings for misconfigured options.
+ * Validates CDN props — synth-time hard errors for shapes CloudFormation
+ * would only reject at deploy.
  */
 function validateCdnProps(props) {
     const hasCertificate = !!(props.certificate || props.certificateArn);
-    // Validate certificate region warning
-    if (hasCertificate && props.domainNames && props.domainNames.length > 0) {
-        FjallLogger.info("CloudFront certificates must be in us-east-1 region. " +
-            "Ensure your certificate was created in us-east-1.");
+    // CloudFront accepts viewer certificates from us-east-1 only. A literal
+    // ARN is inspectable at synth (design H3/D3 — the old advisory log is
+    // replaced by real us-east-1 provisioning in the patterns; this assert
+    // covers the BYO-ARN escape hatch), so fail here with the cure rather
+    // than at CloudFormation with InvalidViewerCertificate.
+    if (props.certificateArn !== undefined &&
+        !Token.isUnresolved(props.certificateArn)) {
+        const certificateRegion = props.certificateArn.split(":")[3];
+        if (certificateRegion !== "us-east-1") {
+            throw new Error(`CDN 'certificateArn' is in region '${certificateRegion}' ` +
+                `(got '${props.certificateArn}'). CloudFront accepts viewer ` +
+                "certificates from us-east-1 only — pass the ARN of a us-east-1 " +
+                "certificate, or set the pattern's domain zone identity so it " +
+                "provisions one.");
+        }
     }
-    // Validate domain names require certificate
+    // Aliases without a viewer certificate fail at CloudFormation deploy; fail
+    // at synth with the cure instead.
     if (props.domainNames && props.domainNames.length > 0 && !hasCertificate) {
-        FjallLogger.warn("'domainNames' provided but no 'certificate' specified. " +
-            "Custom domain names require an ACM certificate in us-east-1.");
+        throw new Error(`CDN 'domainNames' [${props.domainNames.join(", ")}] were provided ` +
+            "without a certificate. CloudFront serves custom domain names only " +
+            "with a us-east-1 ACM certificate — pass 'certificate' or " +
+            "'certificateArn', or configure the pattern's 'domain' with a zone " +
+            "identity so it provisions one.");
     }
     // Validate ALB origin
     if (props.originType === "alb") {

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

@@ -25,7 +25,7 @@ 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 { validateSecretName } from "../../resources/aws/compute/ecsValidation.js";
+import { validateEcsDomainConfig, validateSecretName } from "../../resources/aws/compute/ecsValidation.js";
 import { COMPUTE_DEFAULTS, collectImportedSecretNames } from "./compute.js";
 import { isHookMigrations } from "./computeEcsTypes.js";
 export { ScalingType } from "./computeEcsTypes.js";
@@ -81,6 +81,11 @@ function validateSeparateTaskDef(serviceName, separateTaskDef) {
  * Extracted for clarity and detail parity with database/network patterns.
  */
 export function validateEcsProps(props) {
+    // Mirror of the resources-layer domainConfig checks (H8 legacy `region`
+    // rejection, routingPolicy shape) — defence-in-depth per generator-standards
+    // § "Validate at the Lowest Layer the Field Belongs To". The cluster name is
+    // the construct id, unavailable here, so errors prefix with the domain name.
+    validateEcsDomainConfig(props.cluster?.domainConfig);
     // Validate services array exists and is not empty
     if (!props.services || props.services.length === 0) {
         throw new Error("At least one service must be specified in 'services' array.");

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

@@ -522,6 +522,10 @@ export interface EcsClusterConfig {
      * Domain for HTTPS access.
      * - Omit: ALB created with default DNS (*.elb.amazonaws.com)
      * - Specified: Creates ACM certificate + Route53 DNS A record
+     *
+     * Requires `domainConfig` to name a zone source (`managedDomain` or
+     * `hostedZone`) — Fjall never creates a hosted zone inside an app stack
+     * (design D1/H1), so a bare `domain` with no zone source throws at synth.
      */
     domain?: string;
     /**
@@ -538,9 +542,10 @@ export interface EcsClusterConfig {
      */
     directAccess?: boolean;
     /**
-     * Advanced domain configuration for routing policies (latency, weighted, geo).
-     * Only used when domain is specified.
-     * Allows for multi-region deployments with advanced DNS routing.
+     * Domain configuration: zone source (managed domain or imported zone),
+     * certificate, and routing policy (latency via `routingPolicy`, weighted,
+     * geo). Required for any custom domain; enables multi-region deployments
+     * with advanced DNS routing.
      */
     domainConfig?: DomainConfig;
     /**

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

@@ -9,9 +9,18 @@ export interface DelegatedDomainPatternResult {
     readonly manualRecords: ManualRecord[];
 }
 /**
- * Composition for `registrar: "external-delegated"`. Creates a hosted zone
- * for `{delegatedSubdomain}.{zoneName}` — the user adds NS records at their
- * external registrar to delegate the subdomain to Fjall. No cross-account
- * delegation role is required because Fjall is not creating the parent zone.
+ * Composition for `registrar: "external-delegated"` — the delegated-child
+ * topology. Creates a hosted zone for `{delegatedSubdomain}.{zoneName}` and,
+ * when `parentDelegationRoleArn` is present, UPSERTs the child NS into the
+ * parent zone via `CrossAccountZoneDelegationRecord` (D8 child-writes
+ * delegation; same shape as devSubstrate Case 1). The role ARN MUST be a
+ * literal — validated in `validateDomainProps` (VD2-a). When absent, the
+ * user delegates out of band (external registrar / manual NS) and a synth
+ * warning flags that the zone will not resolve until they do.
+ *
+ * `phase: "zone"` early-returns before certificate issuance (R2 cert-hang
+ * guard, shared `DomainDeployPhase` contract with `DevSubstrate`): issuing a
+ * DNS-validated certificate before the delegation has propagated hangs ACM
+ * until CloudFormation rolls back (~1 h).
  */
 export declare function composeDelegatedDomain(scope: Construct, props: ExternalDelegatedProps): DelegatedDomainPatternResult;

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

@@ -1,22 +1,75 @@
+import { Annotations } from "aws-cdk-lib";
+import { Role } from "../../resources/aws/iam/index.js";
 import { HostedZone } from "../../resources/aws/networking/hostedZone.js";
+import { CrossAccountDelegationRecord } from "../../resources/aws/networking/crossAccountDelegationRecord.js";
 import { DomainCertificate } from "../../resources/aws/networking/domainCertificate.js";
 import { composeTypedDnsRecords } from "./dnsRecordComposer.js";
 import { toPascalCase, getSafeZoneName } from "../../utils/capitaliseString.js";
+import { DOMAIN_DEPLOY_DEFAULT_PHASE } from "../../utils/domainTypes.js";
 /**
- * Composition for `registrar: "external-delegated"`. Creates a hosted zone
- * for `{delegatedSubdomain}.{zoneName}` — the user adds NS records at their
- * external registrar to delegate the subdomain to Fjall. No cross-account
- * delegation role is required because Fjall is not creating the parent zone.
+ * Composition for `registrar: "external-delegated"` — the delegated-child
+ * topology. Creates a hosted zone for `{delegatedSubdomain}.{zoneName}` and,
+ * when `parentDelegationRoleArn` is present, UPSERTs the child NS into the
+ * parent zone via `CrossAccountZoneDelegationRecord` (D8 child-writes
+ * delegation; same shape as devSubstrate Case 1). The role ARN MUST be a
+ * literal — validated in `validateDomainProps` (VD2-a). When absent, the
+ * user delegates out of band (external registrar / manual NS) and a synth
+ * warning flags that the zone will not resolve until they do.
+ *
+ * `phase: "zone"` early-returns before certificate issuance (R2 cert-hang
+ * guard, shared `DomainDeployPhase` contract with `DevSubstrate`): issuing a
+ * DNS-validated certificate before the delegation has propagated hangs ACM
+ * until CloudFormation rolls back (~1 h).
  */
 export function composeDelegatedDomain(scope, props) {
     const effectiveZone = `${props.delegatedSubdomain}.${props.zoneName}`;
     const safeZone = toPascalCase(getSafeZoneName(effectiveZone));
     const hostedZoneConstruct = new HostedZone(scope, `${safeZone}HostedZone`, {
         zoneName: effectiveZone,
+        // The PARENT account owns the delegation role — this is the child.
         createDelegationRole: false,
         costAllocationEnvironment: props.costAllocationEnvironment,
         costAllocationDomain: props.zoneName
     });
+    // D8 child-writes delegation. The in-stack custom resource assumes the
+    // parent account's DelegationRole by LITERAL ARN (Role.fromRoleArn) — NOT
+    // Fn.importValue, which resolves same-account only (VD2-a). The parent
+    // DelegationRole trusts the whole org (OrganizationPrincipal), so a child
+    // account can assume it. The CLI injects the ARN via
+    // ManagedDomainBinding.delegationRoleArn at deploy time.
+    if (props.parentDelegationRoleArn !== undefined) {
+        const parentRole = Role.fromRoleArn(scope, `${safeZone}ParentDelegationRole`, props.parentDelegationRoleArn);
+        new CrossAccountDelegationRecord(scope, `${safeZone}DelegationRecord`, {
+            delegationRole: parentRole,
+            delegatedZone: hostedZoneConstruct.hostedZone,
+            delegatedZoneName: effectiveZone,
+            parentHostedZoneName: props.zoneName,
+            costAllocationEnvironment: props.costAllocationEnvironment,
+            costAllocationDomain: props.zoneName
+        });
+    }
+    else {
+        Annotations.of(scope).addWarning(`Zone '${effectiveZone}' will not resolve until it is delegated: no ` +
+            `parentDelegationRoleArn was provided, so no NS records are written ` +
+            `into '${props.zoneName}'. Deploy via the Fjall CLI (which injects ` +
+            `the parent DelegationRole ARN from the managed-domain binding) or ` +
+            `add the zone's NS records at the parent registrar manually.`);
+    }
+    const nameServers = hostedZoneConstruct.nameServers ?? [];
+    const records = props.records ?? [];
+    if (records.length > 0) {
+        composeTypedDnsRecords(scope, hostedZoneConstruct.hostedZone, effectiveZone, records);
+    }
+    // Step 2 of the R2 two-step gate: issuing the cert before the delegation
+    // NS has propagated hangs ACM DNS-validation, so "zone" stops here.
+    if ((props.phase ?? DOMAIN_DEPLOY_DEFAULT_PHASE) !== "full") {
+        return {
+            hostedZone: hostedZoneConstruct.hostedZone,
+            certificates: new Map(),
+            nameServers,
+            manualRecords: []
+        };
+    }
     const certificates = new Map();
     (props.certificates ?? []).forEach((cert, index) => {
         const normalised = normaliseCertificate(cert);
@@ -31,10 +84,6 @@ export function composeDelegatedDomain(scope, props) {
         });
         certificates.set(normalised.domainName, dc.certificate);
     });
-    if (props.records && props.records.length > 0) {
-        composeTypedDnsRecords(scope, hostedZoneConstruct.hostedZone, effectiveZone, props.records);
-    }
-    const nameServers = hostedZoneConstruct.nameServers ?? [];
     return {
         hostedZone: hostedZoneConstruct.hostedZone,
         certificates,

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

@@ -1,5 +1,6 @@
 import { Construct } from "constructs";
 import type App from "../../app.js";
+import { type DomainDeployPhase } from "../../utils/domainTypes.js";
 /**
  * Props for the internal `DevSubstrate` construct.
  *
@@ -44,7 +45,7 @@ export interface IDevSubstrateProps {
      * only after the delegated NS has propagated, else ACM DNS-validation hangs.
      * Defaults to `"full"`. Inert unless `domain` is set.
      */
-    readonly phase?: "zone" | "full";
+    readonly phase?: DomainDeployPhase;
     /**
      * Public domain the substrate hangs a `dev.<appDomain>` child zone under. When
      * omitted, the substrate stands up no zone/cert (early milestone — G2 reaches

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

@@ -24,6 +24,7 @@ import { CrossAccountDelegationRecord } from "../../resources/aws/networking/cro
 import { DomainCertificate } from "../../resources/aws/networking/domainCertificate.js";
 import { Role } from "../../resources/aws/iam/role.js";
 import { toPascalCase } from "../../utils/capitaliseString.js";
+import { DOMAIN_DEPLOY_DEFAULT_PHASE } from "../../utils/domainTypes.js";
 import { DEV_AURORA_DEFAULTS } from "../../resources/aws/database/rdsDefaults.js";
 import { DEV_APP_TAG_KEY, DEV_TAG_KEY, DEV_TAG_VALUE } from "../../utils/devSubstrateTags.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -54,12 +55,11 @@ const DEV_SUBSTRATE_PARENT_ROLE_ID = "DevSubstrateParentDelegationRole";
 /** Construct ids for the substrate's wildcard cert + :443 HTTPS listener (A6). */
 const DEV_SUBSTRATE_CERT_ID = "DevSubstrateCertificate";
 const DEV_SUBSTRATE_HTTPS_LISTENER_ID = "DevSubstrateHttpsListener";
-/**
- * Default deploy phase when `phase` is omitted — the cert + :443 listener build.
- * The two-step guard (design R2) sets `"zone"` explicitly for step 1, so the
- * safe default for a single-shot deploy is the complete substrate.
- */
-const DEV_SUBSTRATE_DEFAULT_PHASE = "full";
+// Default deploy phase when `phase` is omitted — the cert + :443 listener
+// build. Shared with the delegated `Domain` topology via
+// `DOMAIN_DEPLOY_DEFAULT_PHASE` (utils/domainTypes.ts): the R2 two-step guard
+// sets `"zone"` explicitly for step 1, so the safe default for a single-shot
+// deploy is the complete substrate.
 /**
  * The substrate's database mode, surfaced to slot-ops as an export so the
  * hand-created G2 slot knows whether to wire Aurora Data-API creds or a
@@ -142,6 +142,11 @@ export class DevSubstrate extends Construct {
             // exposes for the cluster ARN; it returns databaseCluster.clusterArn.
             dbClusterArn: database.getSnapshotTarget().arn,
             dbSecretArn: database.getCredentials().secret.secretArn,
+            // Proxy-less substrate ⇒ getHostEndpoint() is the cluster writer endpoint;
+            // it + the port ride the exports because the dev role cannot rds:Describe*
+            // at runtime to resolve them.
+            dbWriterEndpoint: database.getHostEndpoint(),
+            dbPort: database.getHostPort(),
             slotExecutionRoleArn: slotExecutionRole.roleArn,
             slotRepositoryUri: slotRepository.repositoryUri,
             wakerTargetGroupArn: wakerTargetGroup.targetGroupArn,
@@ -244,7 +249,10 @@ export class DevSubstrate extends Construct {
         // fence-pinned name — the reaper finds it by the subtree fence tags. A pinned
         // name would only reintroduce the 32-char ALB-name truncation dance.
         const loadBalancer = createApplicationLoadBalancer(this, DEV_SUBSTRATE_ALB_ID, { vpc, internetFacing: true, securityGroup: albSecurityGroup });
-        slotSecurityGroup.connections.allowFrom(albSecurityGroup, Port.tcp(DEV_SUBSTRATE_SLOT_PORT), "Dev substrate ALB → slot tasks");
+        slotSecurityGroup.connections.allowFrom(albSecurityGroup, Port.tcp(DEV_SUBSTRATE_SLOT_PORT), 
+        // EC2 SG-rule descriptions reject non-ASCII (allowed set is
+        // `a-zA-Z0-9. _-:/()#,@[]+=&;{}!$*` — no arrow, em-dash, or even `>`).
+        "Dev substrate ALB to slot tasks");
         // Unconditional 404 default — the substrate's only routes are per-slot
         // host-header rules, so an unmatched host must 404, never fall through (the ECS
         // path's 404 is conditional on >=2 routes). The :443 listener + wildcard cert
@@ -327,7 +335,7 @@ export class DevSubstrate extends Construct {
         }
         // Step 2 of the R2 two-step gate: synthesising the cert before the step-1 NS
         // has propagated hangs ACM DNS-validation for hours, so "zone" stops here.
-        if ((props.phase ?? DEV_SUBSTRATE_DEFAULT_PHASE) !== "full")
+        if ((props.phase ?? DOMAIN_DEPLOY_DEFAULT_PHASE) !== "full")
             return { devDomain: childZoneName };
         // exportCertificateArn:false — consumed in-stack by the :443 listener (slots
         // reference the exported LISTENER arn, not the cert), and the wildcard `*.`
@@ -375,6 +383,8 @@ export class DevSubstrate extends Construct {
         emit(this, "AlbCloudWatchName", values.albCloudWatchName);
         emit(databaseScope, "DbClusterArn", values.dbClusterArn);
         emit(databaseScope, "DbSecretArn", values.dbSecretArn);
+        emit(databaseScope, "DbWriterEndpoint", values.dbWriterEndpoint);
+        emit(databaseScope, "DbPort", values.dbPort);
         emit(this, "SlotExecutionRoleArn", values.slotExecutionRoleArn);
         emit(this, "SlotRepositoryUri", values.slotRepositoryUri);
         emit(this, "WakerTargetGroupArn", values.wakerTargetGroupArn);

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

@@ -1,15 +1,8 @@
 import type { Construct } from "constructs";
 import type { IHostedZone } from "aws-cdk-lib/aws-route53";
-import type { DnsRecord, DnsRecordInput } from "./interfaces/domain.js";
+import type { DnsRecord } from "./interfaces/domain.js";
 /**
- * Legacy composer consumed by `DomainFactory` (deleted in Phase 2). Accepts
- * the `DnsRecordInput` shape from the BIND-primary era where ALIAS sentinels
- * live in `value`. Typed targets are not supported here; use
- * `composeTypedDnsRecords` instead.
- */
-export declare function composeDnsRecords(scope: Construct, zone: IHostedZone, zoneName: string, records: DnsRecordInput[]): void;
-/**
- * Typed composer consumed by the new `Domain` construct. Accepts the
+ * Typed composer consumed by the `Domain` construct. Accepts the
  * discriminated `DnsRecord` union (`StandardRecord | AliasRecord`).
  *
  * `AliasRecord` entries MUST carry a `target` produced by `fjallApp()`,