@fjall/components-infrastructure 2.33.0 → 3.0.0

package/dist/lib/app.d.ts

@@ -3,7 +3,7 @@ import { type CloudAssembly } from "aws-cdk-lib/cx-api";
 import { type Construct } from "constructs";
 import { type IVpc } from "aws-cdk-lib/aws-ec2";
 import { type Role } from "aws-cdk-lib/aws-iam";
-import { AwsStack } from "./resources/index.js";
+import { AwsStack, type AwsStackProps } from "./resources/index.js";
 import { type Ecr } from "./resources/aws/storage/ecr.js";
 import { type AnyDatabase } from "./patterns/aws/database.js";
 import { type INetworkProps, type Network } from "./patterns/aws/network.js";
@@ -123,8 +123,10 @@ export declare class App extends CdkApp {
      *
      * @param key - The key of the stack
      * @param dependencies - The stack(s) that this stack depends on
+     * @param props - Stack props applied on first creation only (cached
+     *                stacks are returned as-is)
      */
-    getStack(key: string, dependencies?: AwsStack | AwsStack[]): AwsStack;
+    getStack(key: string, dependencies?: AwsStack | AwsStack[], props?: AwsStackProps): AwsStack;
     /**
      * Retrieve default compute stack - named as `${this.name}Compute`
      *
@@ -162,6 +164,21 @@ export declare class App extends CdkApp {
      * require VPC, but we maintain consistent stack dependency patterns.
      */
     getDefaultMessagingStack(): AwsStack;
+    /**
+     * Retrieve the app-owned us-east-1 certificate stack — named
+     * `${this.name}UsEast1Certificates` (domain gold-plating D3, BYO path).
+     *
+     * CloudFront accepts viewer certificates from us-east-1 only, so
+     * CloudFront-consuming patterns (staticsite, payload) whose app deploys to
+     * another region provision their DomainCertificate here; the distribution
+     * in the Cdn stack consumes the ARN through CDK cross-region references.
+     *
+     * `crossRegionReferences: true` must be set on BOTH the producing and the
+     * consuming stack; both get it at construction (the Cdn stack in
+     * getDefaultCdnStack, this stack here) and the emitted
+     * Custom::CrossRegionExportWriter/Reader pair is pinned by template test.
+     */
+    getUsEast1CertificateStack(): AwsStack;
     /**
      * Get a VPC by name. If no name is provided, returns the default VPC.
      *

package/dist/lib/app.js

@@ -18,8 +18,10 @@ import AuditRoleFactory from "./resources/aws/audit/auditRole.js";
 import { FJALL_AUDIT_CONFIG } from "./config/audit.js";
 import { FjallLogger } from "./utils/validationLogger.js";
 import { getManifestCollector, writeManifest } from "./utils/manifestWriter.js";
+import { resetDnsRecordRegistry } from "./utils/dnsRecordRegistry.js";
 import { toPascalCase, toKebab } from "./utils/capitaliseString.js";
 import { COST_ALLOCATION_TAGS } from "./utils/costAllocationTags.js";
+import { DEFAULT_ORG_ID, resolveOrgId } from "./utils/cdkContext.js";
 /**
  * The basic corner-stone of all Fjall-hosted applications.
  *  This class is a singleton and should be used to create and manage
@@ -167,6 +169,10 @@ export class App extends CdkApp {
     }
     static resetForTesting() {
         App.instance = null;
+        // App-scoped synth state resets with the App singleton — the DNS
+        // record-collision registry (D5) follows the manifest-collector lifecycle
+        // without requiring a third per-test reset call.
+        resetDnsRecordRegistry();
     }
     /**
      * Retrieve a stack by key. If the stack does not exist, it will be created.
@@ -174,8 +180,10 @@ export class App extends CdkApp {
      *
      * @param key - The key of the stack
      * @param dependencies - The stack(s) that this stack depends on
+     * @param props - Stack props applied on first creation only (cached
+     *                stacks are returned as-is)
      */
-    getStack(key, dependencies) {
+    getStack(key, dependencies, props) {
         // Apply the aspect once before creating the first stack
         if (!this.aspectApplied &&
             Object.keys(this.stacks).length === 0 &&
@@ -183,7 +191,7 @@ export class App extends CdkApp {
             this.applyTagsAspect();
         }
         if (!this.stacks[key]) {
-            this.stacks[key] = new AwsStack(key, dependencies);
+            this.stacks[key] = new AwsStack(key, dependencies, props);
         }
         return this.stacks[key];
     }
@@ -224,7 +232,10 @@ export class App extends CdkApp {
      * stack is synthesised.
      */
     getDefaultCdnStack() {
-        return this.getStack(`${this.stackPrefix}Cdn`, this.networkDisabled ? undefined : this.getDefaultNetworkStack());
+        // crossRegionReferences is enabled at creation so the Cdn stack can
+        // consume a us-east-1 certificate (domain gold-plating D3, BYO path).
+        // The flag is inert unless a cross-region reference is synthesised.
+        return this.getStack(`${this.stackPrefix}Cdn`, this.networkDisabled ? undefined : this.getDefaultNetworkStack(), { crossRegionReferences: true });
     }
     /**
      * Retrieve default messaging stack - named as `${this.name}Messaging`
@@ -236,6 +247,39 @@ export class App extends CdkApp {
     getDefaultMessagingStack() {
         return this.getStack(`${this.stackPrefix}Messaging`, this.getDefaultNetworkStack());
     }
+    /**
+     * Retrieve the app-owned us-east-1 certificate stack — named
+     * `${this.name}UsEast1Certificates` (domain gold-plating D3, BYO path).
+     *
+     * CloudFront accepts viewer certificates from us-east-1 only, so
+     * CloudFront-consuming patterns (staticsite, payload) whose app deploys to
+     * another region provision their DomainCertificate here; the distribution
+     * in the Cdn stack consumes the ARN through CDK cross-region references.
+     *
+     * `crossRegionReferences: true` must be set on BOTH the producing and the
+     * consuming stack; both get it at construction (the Cdn stack in
+     * getDefaultCdnStack, this stack here) and the emitted
+     * Custom::CrossRegionExportWriter/Reader pair is pinned by template test.
+     */
+    getUsEast1CertificateStack() {
+        const key = `${this.stackPrefix}UsEast1Certificates`;
+        if (!this.stacks[key]) {
+            const account = process.env.CDK_DEFAULT_ACCOUNT;
+            if (!account) {
+                throw new Error(`App '${this.name}': the us-east-1 certificate stack needs a ` +
+                    "concrete account (got CDK_DEFAULT_ACCOUNT undefined). " +
+                    "Cross-region references resolve only between env-pinned stacks " +
+                    "— deploy through the Fjall CLI, or export CDK_DEFAULT_ACCOUNT " +
+                    "and CDK_DEFAULT_REGION before synthesising.");
+            }
+            this.stacks[key] = new AwsStack(key, undefined, {
+                accountId: account,
+                region: "us-east-1",
+                crossRegionReferences: true
+            });
+        }
+        return this.stacks[key];
+    }
     /**
      * Get a VPC by name. If no name is provided, returns the default VPC.
      *
@@ -702,6 +746,15 @@ export class App extends CdkApp {
     }
     applyTagsAspect() {
         if (!this.aspectApplied && Object.keys(this.globalTags).length > 0) {
+            // Owner fallback resolves lazily HERE, not in initialiseStandardTags:
+            // at construction the orgId context may not be set yet, and an explicit
+            // addTags owner must win — by this point it is already in globalTags.
+            if (this.globalTags[COST_ALLOCATION_TAGS.OWNER] === undefined) {
+                const orgId = resolveOrgId(this.node);
+                if (orgId !== undefined && orgId !== DEFAULT_ORG_ID) {
+                    this.globalTags[COST_ALLOCATION_TAGS.OWNER] = orgId;
+                }
+            }
             // Apply standard tags using Tags.of(this).add()
             for (const [key, value] of Object.entries(this.globalTags)) {
                 Tags.of(this).add(key, value);
@@ -748,7 +801,11 @@ export class App extends CdkApp {
         return this.manifestCollector;
     }
     synth(options) {
-        // Call parent synth first
+        // Tagging is an invariant of synthesis, not of getStack(): governance
+        // stacks (Organisation/Account/Platform) and raw `extends Stack` classes
+        // attach directly to the App and never call getStack(), so without this
+        // they synthesise untagged. Idempotent via the aspectApplied guard.
+        this.applyTagsAspect();
         const assembly = super.synth(options);
         // After synthesis, write Fjall manifest to cdk.out
         try {

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

@@ -1,4 +1,4 @@
-import { CfnOutput, Stack } from "aws-cdk-lib";
+import { CfnOutput, Stack, Tags } from "aws-cdk-lib";
 import { EcrDefaultImage, SharedAlarmTopic } from "../../config/aws/index.js";
 import { ManagementEventsTrail } from "../../config/aws/cloudTrail.js";
 import { OidcConnector } from "../../config/aws/oidcConnector.js";
@@ -6,6 +6,7 @@ import { AccountMonitoringRole } from "../../config/aws/accountMonitoringRole.js
 import { AccountAuditRole } from "../../config/aws/accountAuditRole.js";
 import { CDK_CONTEXT_KEYS, resolveAccountTrailState } from "../../utils/cdkContext.js";
 import { getConfig } from "../../utils/getConfig.js";
+import { COST_ALLOCATION_TAGS } from "../../utils/costAllocationTags.js";
 import { DisasterRecovery } from "../../config/aws/disasterRecovery.js";
 import { S3BlockPublicAccess } from "../../config/aws/s3BlockPublicAccess.js";
 import { EbsDefaultEncryption } from "../../config/aws/ebsDefaultEncryption.js";
@@ -28,6 +29,10 @@ export class Account extends Stack {
         }
         const env = props.env ?? { region, account: accountId };
         super(scope, id, { ...props, env });
+        // Governance apps never name the App, so the App-level service tag would
+        // read "FjallApp"; the stack-scope tag wins over App scope and names the
+        // governance tier instead ("Organisation"/"Account"/"Platform").
+        Tags.of(this).add(COST_ALLOCATION_TAGS.SERVICE, id);
         this.resolvedRegion = region ?? this.region;
         const orgId = this.node.tryGetContext(CDK_CONTEXT_KEYS.ORG_ID);
         if (orgId) {

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

@@ -1,26 +1,25 @@
 import type { Construct } from "constructs";
 import type { IHostedZone } from "aws-cdk-lib/aws-route53";
 import type { ICertificate } from "aws-cdk-lib/aws-certificatemanager";
-import type { ManualRecord, Route53ApexProps, SubdomainDelegation } from "./interfaces/domain.js";
+import type { ManualRecord, Route53ApexProps } from "./interfaces/domain.js";
 export interface ApexDomainPatternResult {
     readonly hostedZone: IHostedZone;
     readonly certificates: Map<string, ICertificate>;
     readonly nameServers: string[] | undefined;
     readonly manualRecords: ManualRecord[];
-    readonly delegations: SubdomainDelegation[];
 }
 /**
  * Composition for `registrar: "route53"`. Creates (or imports) the apex
- * `HostedZone`, wires child-account delegations via `NsRecord` (pointing at
- * each child's nameservers published as exports), and composes all user
- * records + certificates.
+ * `HostedZone` and composes all user records + certificates.
  *
- * Delegation mechanism: the child Fjall account scaffolds its own
- * `HostedZone`, and the parent simply writes NS records pointing at the
- * child's nameservers (Fn.importValue of the child stack's nameservers
- * output). This differs from the legacy `DomainDelegation` pattern, which
- * uses `CrossAccountZoneDelegationRecord` to create the child HZ from the
- * parent via IAM assume-role. Both patterns are valid for their respective
- * semantics — see R10 in the Phase 1 plan.
+ * Delegation direction (D8): child writes NS. The apex zone's contribution
+ * to delegation is the org-gated `DelegationRole` the `HostedZone` wrapper
+ * creates on the create path — the delegated child `Domain` assumes that
+ * role by LITERAL ARN (`parentDelegationRoleArn`) and UPSERTs its own NS
+ * records into this zone via `CrossAccountZoneDelegationRecord`. The old
+ * parent-writes `delegations[]` path (NS records from `Fn.importValue` of
+ * child nameserver exports) was removed with the H13 legacy layer: it was
+ * export-locked, child-first-deploy-ordered, and removal required a parent
+ * redeploy.
  */
 export declare function composeApexDomain(scope: Construct, props: Route53ApexProps): ApexDomainPatternResult;

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

@@ -1,24 +1,21 @@
-import { Fn } from "aws-cdk-lib";
-import { getDomainExportNames } from "@fjall/util";
 import { HostedZone } from "../../resources/aws/networking/hostedZone.js";
 import { DomainCertificate } from "../../resources/aws/networking/domainCertificate.js";
-import { NsRecord } from "../../resources/aws/networking/dnsRecord/index.js";
 import { composeTypedDnsRecords } from "./dnsRecordComposer.js";
 import { toPascalCase, getSafeZoneName } from "../../utils/capitaliseString.js";
 import { resolveOrgId } from "../../utils/cdkContext.js";
 /**
  * Composition for `registrar: "route53"`. Creates (or imports) the apex
- * `HostedZone`, wires child-account delegations via `NsRecord` (pointing at
- * each child's nameservers published as exports), and composes all user
- * records + certificates.
+ * `HostedZone` and composes all user records + certificates.
  *
- * Delegation mechanism: the child Fjall account scaffolds its own
- * `HostedZone`, and the parent simply writes NS records pointing at the
- * child's nameservers (Fn.importValue of the child stack's nameservers
- * output). This differs from the legacy `DomainDelegation` pattern, which
- * uses `CrossAccountZoneDelegationRecord` to create the child HZ from the
- * parent via IAM assume-role. Both patterns are valid for their respective
- * semantics — see R10 in the Phase 1 plan.
+ * Delegation direction (D8): child writes NS. The apex zone's contribution
+ * to delegation is the org-gated `DelegationRole` the `HostedZone` wrapper
+ * creates on the create path — the delegated child `Domain` assumes that
+ * role by LITERAL ARN (`parentDelegationRoleArn`) and UPSERTs its own NS
+ * records into this zone via `CrossAccountZoneDelegationRecord`. The old
+ * parent-writes `delegations[]` path (NS records from `Fn.importValue` of
+ * child nameserver exports) was removed with the H13 legacy layer: it was
+ * export-locked, child-first-deploy-ordered, and removal required a parent
+ * redeploy.
  */
 export function composeApexDomain(scope, props) {
     const safeZone = toPascalCase(getSafeZoneName(props.zoneName));
@@ -51,22 +48,6 @@ export function composeApexDomain(scope, props) {
     if (props.records && props.records.length > 0) {
         composeTypedDnsRecords(scope, hostedZoneConstruct.hostedZone, props.zoneName, props.records);
     }
-    const delegations = props.delegations ?? [];
-    delegations.forEach((delegation, index) => {
-        const childZoneName = `${delegation.subdomain}.${props.zoneName}`;
-        const safeChild = toPascalCase(getSafeZoneName(childZoneName));
-        const childExports = getDomainExportNames(childZoneName);
-        // Cross-phase dependency: child stack must deploy first; CFN fails here
-        // at deploy if the nameservers export does not yet exist.
-        const nameserversToken = Fn.importValue(childExports.nameservers);
-        new NsRecord(scope, `${safeZone}Delegation${safeChild}${index}`, {
-            zone: hostedZoneConstruct.hostedZone,
-            zoneName: props.zoneName,
-            recordName: delegation.subdomain,
-            // Fn.split returns a list token suitable for a multi-value NS record.
-            values: Fn.split(",", nameserversToken)
-        });
-    });
     return {
         hostedZone: hostedZoneConstruct.hostedZone,
         certificates,
@@ -75,8 +56,7 @@ export function composeApexDomain(scope, props) {
         nameServers: hostedZoneConstruct.isImported
             ? undefined
             : (hostedZoneConstruct.nameServers ?? undefined),
-        manualRecords: [],
-        delegations
+        manualRecords: []
     };
 }
 function normaliseCertificate(cert) {

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

@@ -13,6 +13,7 @@ import { resolveImportedSecret } from "../../resources/aws/secrets/index.js";
 import App from "../../app.js";
 import EcsCluster from "../../resources/aws/compute/ecs.js";
 import { createScheduledTaskDefinition, createMigrationTaskDefinition } from "../../resources/aws/compute/ecsTaskDefinition.js";
+import { DEFAULT_LOG_RETENTION } from "../../resources/aws/compute/ecsConstants.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";
@@ -24,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";
@@ -80,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.");
@@ -924,13 +930,16 @@ export class EcsCompute extends Construct {
                 });
             }
         }
+        // `logRetention` must not reach the driver: AwsLogDriver.bind() creates
+        // a raw RETAIN LogGroup inside aws-cdk-lib, escaping the env-aware
+        // removal default (D17).
+        const logGroup = entry.logGroup ??
+            new LogGroup(this, `${id}${toPascalCase(entry.name)}LogGroup`, {
+                retention: entry.logRetention ?? DEFAULT_LOG_RETENTION
+            });
         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
-            })
+            logGroup
         });
         const container = taskDef.addContainer(`${id}${toPascalCase(entry.name)}Container`, {
             image: entry.image,

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

@@ -501,7 +501,11 @@ export interface EcsScheduledTaskConfig {
     secrets?: Record<string, EcsSecret>;
     /** Pre-existing CDK log group. Mutually exclusive with `logRetention`. */
     logGroup?: ILogGroup;
-    /** When `logGroup` is omitted, the awsLogs driver creates one with this retention. */
+    /**
+     * When `logGroup` is omitted, an explicit framework log group is created
+     * with this retention (default: `DEFAULT_LOG_RETENTION`) and the env-aware
+     * removal default (D17).
+     */
     logRetention?: RetentionDays;
     securityGroups?: ISecurityGroup[];
     subnetSelection?: SubnetSelection;
@@ -518,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;
     /**
@@ -534,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