@fjall/components-infrastructure 2.34.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,6 +18,7 @@ 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";
@@ -168,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.
@@ -175,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 &&
@@ -184,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];
     }
@@ -225,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`
@@ -237,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.
      *

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

@@ -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()`,