@fjall/components-infrastructure 2.34.0 → 3.0.0

package/dist/lib/resources/aws/compute/ecsNetworking.js

@@ -1,11 +1,17 @@
 import { ApplicationProtocol, ListenerAction } from "aws-cdk-lib/aws-elasticloadbalancingv2";
 import { Port } from "aws-cdk-lib/aws-ec2";
-import { CfnOutput, Duration, Fn } from "aws-cdk-lib";
-import { Certificate, CertificateValidation } from "aws-cdk-lib/aws-certificatemanager";
-import { ARecord, HostedZone as AWSHostedZone, RecordTarget } from "aws-cdk-lib/aws-route53";
+import { CfnOutput, Duration, Fn, Stack } from "aws-cdk-lib";
+import { createHash } from "node:crypto";
+import { Certificate } from "aws-cdk-lib/aws-certificatemanager";
+import { HostedZone as AWSHostedZone } from "aws-cdk-lib/aws-route53";
 import { LoadBalancerTarget } from "aws-cdk-lib/aws-route53-targets";
-import { HostedZone as FjallHostedZone } from "../networking/hostedZone.js";
+import { DomainCertificate } from "../networking/domainCertificate.js";
+import { AliasRecord } from "../networking/dnsRecord/aliasRecord.js";
 import { SecurityGroup } from "../networking/securityGroup.js";
+import { DNS_APEX, isManagedDomainBinding, isWithinZone } from "../../../utils/domainTypes.js";
+import { readInjectedManagedDomainBinding } from "../../../utils/managedDomainContext.js";
+import { getSafeZoneName, toPascalCase } from "../../../utils/capitaliseString.js";
+import { FjallLogger } from "../../../utils/validationLogger.js";
 import { isServiceEc2 } from "./ecsTaskDefinition.js";
 import { createApplicationLoadBalancer } from "./applicationLoadBalancer.js";
 import { addRoutingListener } from "./listenerRouting.js";
@@ -97,6 +103,60 @@ export function addLoadBalancerListener(ctx, loadBalancer, certificate) {
         default404: willHaveMultipleRoutes || noServicePorts
     });
 }
+/**
+ * Reproduce the CloudFormation logical ID CDK allocated for the pre-wrapper
+ * raw `ARecord` at `<scope>/<id>` — i.e. for its `CfnRecordSet` default child
+ * at `<scope>/<id>/Resource` (the `makeUniqueId` algorithm from aws-cdk-lib
+ * `core/lib/private/uniqueid.ts`, pinned byte-for-byte by
+ * `ecsDomainBaseline.test.ts`). The `AliasRecord` wrapper nests its RecordSet
+ * one level deeper (`<scope>/<id>/Record/Resource`), which would re-hash the
+ * logical ID and churn every deployed apex record — a logical-ID change on a
+ * live RecordSet is a create-then-delete replacement that Route53 rejects
+ * ("record set already exists"). Per the flipless-retain-flip no-churn
+ * principle we pin the legacy ID via `overrideLogicalId` instead.
+ */
+function preWrapperLogicalId(scope, id) {
+    const stack = Stack.of(scope);
+    // "Resource" — the raw L2's CfnRecordSet default-child id — is hidden from
+    // the human-readable portion below but participates in the hash.
+    const components = [id, "Resource"];
+    for (let current = scope; current !== undefined && current !== stack; current = current.node.scope) {
+        components.unshift(current.node.id);
+    }
+    // "Default" components are hidden from both the human-readable portion and
+    // the hash; "Resource" only from the human-readable portion.
+    const visible = components.filter((c) => c !== "Default");
+    const sole = visible.length === 1 ? visible[0] : undefined;
+    if (sole !== undefined) {
+        const candidate = sole.replace(/[^A-Za-z0-9]/g, "");
+        if (candidate.length <= 255)
+            return candidate;
+    }
+    const deduped = [];
+    for (const component of visible) {
+        const previous = deduped[deduped.length - 1];
+        if (previous === undefined || !previous.endsWith(component)) {
+            deduped.push(component);
+        }
+    }
+    const hash = createHash("md5")
+        .update(visible.join("/"))
+        .digest("hex")
+        .slice(0, 8)
+        .toUpperCase();
+    const human = deduped
+        .filter((c) => c !== "Resource")
+        .map((c) => c.replace(/[^A-Za-z0-9]/g, ""))
+        .join("")
+        .slice(0, 240);
+    return human + hash;
+}
+/** Record label for `fqdn` relative to `zoneName` (apex → `@`). */
+function recordLabelWithin(fqdn, zoneName) {
+    return fqdn === zoneName
+        ? DNS_APEX
+        : fqdn.slice(0, fqdn.length - zoneName.length - 1);
+}
 export function addHostedZone(ctx, loadBalancer) {
     const props = ctx.props;
     const domainConfig = props.cluster?.domainConfig;
@@ -105,43 +165,129 @@ export function addHostedZone(ctx, loadBalancer) {
     if (!domainName)
         return {};
     let hostedZone;
+    let zoneName;
     let certificate;
-    let aRecord;
-    // Managed domain: import zone and cert from domain stack via Fn.importValue
-    if (domainConfig?.managedDomain) {
-        const managed = domainConfig.managedDomain;
-        hostedZone = AWSHostedZone.fromHostedZoneAttributes(ctx.scope, `${props.clusterName}ManagedHostedZone`, {
-            hostedZoneId: Fn.importValue(managed.hostedZoneIdExport),
-            zoneName: managed.zoneName
-        });
-        certificate = Certificate.fromCertificateArn(ctx.scope, `${props.clusterName}ManagedCertificate`, Fn.importValue(managed.certificateArnExport));
+    // D2 — explicit props.managedDomain wins over the CLI-injected context
+    // binding (explicit beats injected); the context read sits ahead of the
+    // BYO domainConfig.hostedZone chain. Bare-CDK synth has no context entry.
+    const managed = domainConfig?.managedDomain ??
+        readInjectedManagedDomainBinding(ctx.scope.node, domainName, `Cluster '${props.clusterName}'`);
+    if (managed) {
+        zoneName = managed.zoneName;
+        if (isManagedDomainBinding(managed)) {
+            // D2 binding: concrete values injected by the CLI at deploy time —
+            // literals cross accounts and regions where Fn.importValue cannot.
+            hostedZone = AWSHostedZone.fromHostedZoneAttributes(ctx.scope, `${props.clusterName}ManagedHostedZone`, {
+                hostedZoneId: managed.hostedZoneId,
+                zoneName: managed.zoneName
+            });
+            if (managed.certificateArn !== undefined) {
+                certificate = Certificate.fromCertificateArn(ctx.scope, `${props.clusterName}ManagedCertificate`, managed.certificateArn);
+            }
+        }
+        else {
+            // Export-name fallback (bare-CDK synth): same account, same region only.
+            hostedZone = AWSHostedZone.fromHostedZoneAttributes(ctx.scope, `${props.clusterName}ManagedHostedZone`, {
+                hostedZoneId: Fn.importValue(managed.hostedZoneIdExport),
+                zoneName: managed.zoneName
+            });
+            certificate = Certificate.fromCertificateArn(ctx.scope, `${props.clusterName}ManagedCertificate`, Fn.importValue(managed.certificateArnExport));
+        }
     }
-    else if (!domainConfig?.hostedZone) {
-        const fjallHostedZone = new FjallHostedZone(ctx.scope, `${props.clusterName}HostedZone`, {
-            zoneName: domainName
-        });
-        hostedZone = fjallHostedZone.hostedZone;
+    else if (domainConfig?.hostedZone) {
+        hostedZone = domainConfig.hostedZone.hostedZone;
+        zoneName = domainConfig.hostedZone.zoneName;
     }
     else {
-        hostedZone = domainConfig.hostedZone.hostedZone;
+        // H1/D1 — Fjall never creates a hosted zone inside an app stack: it would
+        // be undelegated (its nameservers are never published), ACM DNS validation
+        // would hang until CloudFormation rolls back (~1 h), and destroying the
+        // stack would delete the zone.
+        throw new Error(`Cluster '${props.clusterName}': domain '${domainName}' names no hosted zone source ` +
+            "(got neither domainConfig.managedDomain nor domainConfig.hostedZone). " +
+            "Fjall never creates a hosted zone inside an app stack — it would be undelegated, " +
+            "so certificate validation hangs until rollback and stack destruction deletes the zone. " +
+            "Reference a managed domain (domainConfig.managedDomain) or import the zone explicitly " +
+            "(domainConfig.hostedZone: HostedZoneFactory.import(stack, hostedZoneId, zoneName)).");
+    }
+    if (!isWithinZone(domainName, zoneName)) {
+        throw new Error(`Cluster '${props.clusterName}': domain '${domainName}' is outside hosted zone ` +
+            `'${zoneName}' (got zone '${zoneName}'). A record written here would never resolve. ` +
+            `Use a zone that contains '${domainName}', or manage the domain from its own Domain stack.`);
     }
+    // H7 — host-routing completeness: every `routing: { host }` needs an alias
+    // record and (on the cluster-minted certificate) a SAN, or the deploy goes
+    // green and TLS fails at the first request.
+    const routedHosts = [];
+    for (const service of props.services) {
+        const rules = Array.isArray(service.routing)
+            ? service.routing
+            : service.routing
+                ? [service.routing]
+                : [];
+        for (const rule of rules) {
+            if (rule.host === undefined)
+                continue;
+            if (!isWithinZone(rule.host, zoneName)) {
+                throw new Error(`Cluster '${props.clusterName}', service '${service.name}': routing.host ` +
+                    `'${rule.host}' is outside hosted zone '${zoneName}' (got '${rule.host}'). ` +
+                    "Its alias record and certificate SAN cannot be created here, so TLS would " +
+                    `fail after a green deploy. Use a host under '${zoneName}', or serve it ` +
+                    "from its own Domain stack.");
+            }
+            if (!routedHosts.includes(rule.host))
+                routedHosts.push(rule.host);
+        }
+    }
+    const subjectAlternativeNames = routedHosts.filter((h) => h !== domainName);
     if (domainConfig?.certificate) {
         certificate = domainConfig.certificate;
     }
-    else if (!domainConfig?.managedDomain) {
-        certificate = new Certificate(ctx.scope, `${props.clusterName}Certificate`, {
+    if (certificate !== undefined) {
+        if (subjectAlternativeNames.length > 0) {
+            FjallLogger.warn(`Cluster '${props.clusterName}': host-routed services rely on the supplied ` +
+                `certificate covering ${subjectAlternativeNames.join(", ")} — Fjall cannot ` +
+                "add SANs to an imported certificate. Ensure it carries these names or a " +
+                "matching wildcard, or TLS fails for those hosts.");
+        }
+    }
+    else {
+        certificate = new DomainCertificate(ctx.scope, `${props.clusterName}Certificate`, {
             domainName,
-            validation: CertificateValidation.fromDns(hostedZone)
-        });
+            ...(subjectAlternativeNames.length > 0 && { subjectAlternativeNames }),
+            hostedZone,
+            // Honest environment tag: the cluster's app already tags the
+            // account-stage-resolved environment tree-wide (App.globalTags via
+            // getConfig); the mint must inherit it, not out-tag it with the
+            // resource-level "management" default. No sniffing here — any local
+            // re-resolution (context/env-var channels) can diverge from the app
+            // cascade, and did on the first live plan.
+            inheritCostAllocationEnvironment: true,
+            // The cert is consumed in-stack by the ALB listener; exporting would
+            // collide with a managed-domain/apex stack that owns the domain's
+            // export names.
+            exportCertificateArn: false
+        }).certificate;
     }
-    if (domainConfig) {
-        const region = "region" in domainConfig ? domainConfig.region : undefined;
-        const weight = "weight" in domainConfig ? domainConfig.weight : undefined;
-        const geoLocation = "geoLocation" in domainConfig ? domainConfig.geoLocation : undefined;
-        const hasRoutingPolicy = !!region || weight !== undefined || !!geoLocation;
-        let setIdentifier = domainConfig.setIdentifier;
-        if (hasRoutingPolicy && !setIdentifier) {
-            if (region) {
+    let aRecord;
+    if (loadBalancer) {
+        const routingPolicy = domainConfig?.routingPolicy;
+        const weight = domainConfig !== undefined && "weight" in domainConfig
+            ? domainConfig.weight
+            : undefined;
+        const geoLocation = domainConfig !== undefined && "geoLocation" in domainConfig
+            ? domainConfig.geoLocation
+            : undefined;
+        const region = routingPolicy?.region;
+        const hasRoutingPolicy = routingPolicy !== undefined ||
+            weight !== undefined ||
+            geoLocation !== undefined;
+        // Identical derivation to the removed `domainConfig.region` era
+        // (`<clusterName><region>`) so migrated clusters emit byte-identical
+        // CloudFormation — pinned by ecsDomainBaseline.test.ts.
+        let setIdentifier = routingPolicy?.setIdentifier ?? domainConfig?.setIdentifier;
+        if (hasRoutingPolicy && setIdentifier === undefined) {
+            if (region !== undefined) {
                 setIdentifier = `${props.clusterName}${region}`;
             }
             else if (weight !== undefined) {
@@ -151,27 +297,46 @@ export function addHostedZone(ctx, loadBalancer) {
                 setIdentifier = `${props.clusterName}Geo`;
             }
         }
-        if (loadBalancer && hostedZone) {
-            aRecord = new ARecord(ctx.scope, `${props.clusterName}ARecord`, {
-                recordName: domainName,
+        const routingProps = {
+            ...(region !== undefined && { region }),
+            ...(weight !== undefined && { weight }),
+            ...(geoLocation !== undefined && { geoLocation }),
+            ...(setIdentifier !== undefined && { setIdentifier })
+        };
+        const apex = new AliasRecord(ctx.scope, `${props.clusterName}ARecord`, {
+            zone: hostedZone,
+            zoneName,
+            recordName: recordLabelWithin(domainName, zoneName),
+            target: new LoadBalancerTarget(loadBalancer, {
+                evaluateTargetHealth: hasRoutingPolicy
+            }),
+            // No-churn adoption: the pre-wrapper raw ARecord carried no comment, so
+            // adding one now would be a property delta on the live production apex
+            // record (flipless-retain-flip principle).
+            omitComment: true,
+            ...routingProps
+        });
+        // Preserve the pre-wrapper logical ID — see preWrapperLogicalId.
+        apex.record.node.defaultChild.overrideLogicalId(preWrapperLogicalId(ctx.scope, `${props.clusterName}ARecord`));
+        aRecord = apex.record;
+        for (const host of routedHosts) {
+            if (host === domainName)
+                continue;
+            const safeHost = toPascalCase(getSafeZoneName(host));
+            new AliasRecord(ctx.scope, `${props.clusterName}${safeHost}AliasRecord`, {
                 zone: hostedZone,
-                target: RecordTarget.fromAlias(new LoadBalancerTarget(loadBalancer, {
+                zoneName,
+                recordName: recordLabelWithin(host, zoneName),
+                target: new LoadBalancerTarget(loadBalancer, {
                     evaluateTargetHealth: hasRoutingPolicy
-                })),
-                region,
-                weight,
-                geoLocation,
-                setIdentifier: setIdentifier
+                }),
+                // Host records inherit the cluster's routing policy: a latency apex
+                // beside a plain host record would collide with the other region's
+                // deploy of the same (name, type) pair.
+                ...routingProps
             });
         }
     }
-    else if (simpleDomain && loadBalancer && hostedZone) {
-        aRecord = new ARecord(ctx.scope, `${props.clusterName}ARecord`, {
-            recordName: domainName,
-            zone: hostedZone,
-            target: RecordTarget.fromAlias(new LoadBalancerTarget(loadBalancer))
-        });
-    }
     return { hostedZone, certificate, aRecord };
 }
 export function addDirectAccessOutputs(ctx, autoScalingGroup) {

package/dist/lib/resources/aws/compute/ecsTypes.d.ts

@@ -17,7 +17,7 @@ import { type Certificate } from "aws-cdk-lib/aws-certificatemanager";
 import { type ConnectionSpec } from "../../../utils/connector.js";
 import { type RemoteConnectionSpec } from "./ecsRemoteConnections.js";
 import { type SecretImport } from "../secrets/index.js";
-import type { ManagedDomainExports } from "../../../utils/domainTypes.js";
+import type { ManagedDomainBinding, ManagedDomainExports } from "../../../utils/domainTypes.js";
 import type { ITopic } from "aws-cdk-lib/aws-sns";
 import type { ILogGroup } from "aws-cdk-lib/aws-logs";
 import type { EcsServiceAlarmThresholds, LogPatternAlarmSpec } from "../monitoring/index.js";
@@ -135,19 +135,65 @@ export interface Ec2CapacityConfig {
      */
     tags?: Record<string, string>;
 }
+/**
+ * Explicit Route53 latency routing policy for the cluster's alias records
+ * (design D7/H8). Replaces the removed `domainConfig.region` field, which
+ * silently converted the record to a latency policy with an auto-derived
+ * `setIdentifier`.
+ */
+export interface EcsLatencyRoutingPolicy {
+    type: "latency";
+    /** AWS region this record answers for. */
+    region: string;
+    /**
+     * Routing-policy record discriminator. Default: `<clusterName><region>` —
+     * the exact derivation the removed `region` field used, so migrating a
+     * deployed cluster emits byte-identical CloudFormation (no churn on the
+     * production apex record).
+     */
+    setIdentifier?: string;
+}
+export type EcsDomainRoutingPolicy = EcsLatencyRoutingPolicy;
 /**
  * Domain configuration for HTTPS and DNS.
+ *
+ * A zone source is REQUIRED: reference a managed domain stack
+ * (`managedDomain`) or import the zone explicitly (`hostedZone`). Fjall never
+ * creates a hosted zone inside an app stack (design D1/H1) — such a zone
+ * would be undelegated, so ACM DNS validation hangs until CloudFormation
+ * rolls back, and destroying the stack would delete the zone.
  */
 export interface DomainBaseConfig {
     domainName: string;
+    /** Explicitly imported zone (BYO path), e.g. `HostedZoneFactory.import(...)`. */
     hostedZone?: FjallHostedZone;
     certificate?: Certificate;
+    /**
+     * Routing-policy record discriminator for the weighted/geolocation
+     * variants. For latency routing prefer `routingPolicy.setIdentifier`;
+     * this field remains the fallback for migrated configs.
+     */
     setIdentifier?: string;
-    /** Import zone and cert from a managed domain stack via Fn.importValue() */
-    managedDomain?: ManagedDomainExports;
-}
-export interface LatencyDomainConfig extends DomainBaseConfig {
-    region: string;
+    /**
+     * Import zone and cert from a managed domain stack. `ManagedDomainBinding`
+     * carries literal values injected by the CLI at deploy time (crosses
+     * accounts and regions); `ManagedDomainExports` is the bare-CDK
+     * `Fn.importValue()` fallback (same account, same region only).
+     */
+    managedDomain?: ManagedDomainExports | ManagedDomainBinding;
+    /**
+     * Explicit Route53 routing policy for the cluster's alias records.
+     * Omit for a plain alias record.
+     */
+    routingPolicy?: EcsDomainRoutingPolicy;
+    /**
+     * @deprecated Removed (design H8). `region` silently converted the record
+     * to a latency routing policy with an auto-derived `setIdentifier`. Declare
+     * it explicitly: `routingPolicy: { type: "latency", region }`. Typed
+     * `never` so old code fails to compile; a runtime guard throws with the
+     * same cure for non-TypeScript callers.
+     */
+    region?: never;
 }
 export interface WeightedDomainConfig extends DomainBaseConfig {
     weight: number;
@@ -155,7 +201,7 @@ export interface WeightedDomainConfig extends DomainBaseConfig {
 export interface GeoLocationDomainConfig extends DomainBaseConfig {
     geoLocation: GeoLocation;
 }
-export type DomainConfig = DomainBaseConfig | LatencyDomainConfig | WeightedDomainConfig | GeoLocationDomainConfig;
+export type DomainConfig = DomainBaseConfig | WeightedDomainConfig | GeoLocationDomainConfig;
 /**
  * A dependency on another container in the same task definition.
  * Maps directly to ECS `ContainerDependency`. See `ContainerDependency` in
@@ -270,6 +316,10 @@ export interface EcsClusterClusterConfig {
      * 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;
     /**
@@ -287,8 +337,9 @@ export interface EcsClusterClusterConfig {
      */
     directAccess?: boolean;
     /**
-     * Domain configuration for advanced routing policies (latency, weighted, geo).
-     * Only used when domain is specified.
+     * Domain configuration: zone source (managed domain or imported zone),
+     * certificate, and routing policy (latency via `routingPolicy`, weighted,
+     * geo). Required for any custom domain.
      */
     domainConfig?: DomainConfig;
     /**

package/dist/lib/resources/aws/compute/ecsValidation.d.ts

@@ -1,4 +1,4 @@
-import type { EcsClusterProps } from "./ecsTypes.js";
+import type { DomainConfig, EcsClusterProps } from "./ecsTypes.js";
 /**
  * Validates ECS cluster props before construction.
  * Pure function — does not depend on class state.
@@ -23,6 +23,19 @@ import type { EcsClusterProps } from "./ecsTypes.js";
  * @throws Error if validation fails
  */
 export declare function validateEcsClusterProps(props: EcsClusterProps): void;
+/**
+ * Domain-config constraints shared by the resources-layer hook
+ * (`validateEcsClusterProps`) and the patterns-layer mirror
+ * (`validateEcsProps` in `lib/patterns/aws/computeEcs.ts`). Pure — safe to
+ * call from both per generator-standards § "Validate at the Lowest Layer the
+ * Field Belongs To". `clusterName` is unavailable at the patterns layer, so
+ * the context prefix falls back to the domain name.
+ *
+ * @param domainConfig - The domain config to validate (no-op when undefined)
+ * @param clusterName - Cluster name for the error-context prefix, if known
+ * @throws Error if validation fails
+ */
+export declare function validateEcsDomainConfig(domainConfig: DomainConfig | undefined, clusterName?: string): void;
 /**
  * Validates an SSM path component for correctness.
  * SSM parameter paths have specific constraints that must be enforced.

package/dist/lib/resources/aws/compute/ecsValidation.js

@@ -26,6 +26,7 @@ import { ScalingType } from "./ecsTypes.js";
  * @throws Error if validation fails
  */
 export function validateEcsClusterProps(props) {
+    validateEcsDomainConfig(props.cluster?.domainConfig, props.clusterName);
     const loadBalancerDisabled = props.cluster?.loadBalancer === false ||
         props.cluster?.directAccess === true;
     // Validate services array
@@ -173,6 +174,56 @@ export function validateEcsClusterProps(props) {
         }
     }
 }
+/**
+ * Domain-config constraints shared by the resources-layer hook
+ * (`validateEcsClusterProps`) and the patterns-layer mirror
+ * (`validateEcsProps` in `lib/patterns/aws/computeEcs.ts`). Pure — safe to
+ * call from both per generator-standards § "Validate at the Lowest Layer the
+ * Field Belongs To". `clusterName` is unavailable at the patterns layer, so
+ * the context prefix falls back to the domain name.
+ *
+ * @param domainConfig - The domain config to validate (no-op when undefined)
+ * @param clusterName - Cluster name for the error-context prefix, if known
+ * @throws Error if validation fails
+ */
+export function validateEcsDomainConfig(domainConfig, clusterName) {
+    if (domainConfig === undefined)
+        return;
+    const context = clusterName !== undefined
+        ? `Cluster '${clusterName}'`
+        : `Domain '${domainConfig.domainName}'`;
+    // H8 — the field is `never`-typed, but JavaScript callers and casts can
+    // still pass it; fail closed with the cure naming the new shape.
+    const legacyRegion = domainConfig.region;
+    if (legacyRegion !== undefined) {
+        throw new Error(`${context}: domainConfig.region has been removed (got '${String(legacyRegion)}') — ` +
+            "it silently converted the record to a latency routing policy with an " +
+            "auto-derived setIdentifier. Declare the policy explicitly: " +
+            `routingPolicy: { type: "latency", region: "${String(legacyRegion)}" }. ` +
+            "The default setIdentifier derivation ('<clusterName><region>') is " +
+            "unchanged, so the migration emits identical CloudFormation.");
+    }
+    const routingPolicy = domainConfig.routingPolicy;
+    if (routingPolicy !== undefined) {
+        if (routingPolicy.type !== "latency") {
+            throw new Error(`${context}: unsupported routingPolicy.type '${String(routingPolicy.type)}' (supported: 'latency'). For weighted or geolocation routing use ` +
+                "the 'weight' / 'geoLocation' domainConfig fields.");
+        }
+        if (typeof routingPolicy.region !== "string" ||
+            routingPolicy.region.trim() === "") {
+            throw new Error(`${context}: routingPolicy.region must be a non-empty AWS region ` +
+                `(got ${JSON.stringify(routingPolicy.region)}). Example: ` +
+                `routingPolicy: { type: "latency", region: "us-east-1" }.`);
+        }
+        const weight = "weight" in domainConfig ? domainConfig.weight : undefined;
+        const geoLocation = "geoLocation" in domainConfig ? domainConfig.geoLocation : undefined;
+        if (weight !== undefined || geoLocation !== undefined) {
+            throw new Error(`${context}: routingPolicy cannot be combined with ` +
+                `'${weight !== undefined ? "weight" : "geoLocation"}' — a record ` +
+                "set carries exactly one routing policy. Remove one of them.");
+        }
+    }
+}
 /**
  * Validates an SSM path component for correctness.
  * SSM parameter paths have specific constraints that must be enforced.

package/dist/lib/resources/aws/networking/dnsRecord/aRecord.js

@@ -1,14 +1,15 @@
 import { Construct } from "constructs";
 import { ARecord as CdkARecord, RecordTarget } from "aws-cdk-lib/aws-route53";
-import { applyDnsRecordTags, defaultDnsComment, resolveFqdn, resolveTtl } from "./dnsRecordBase.js";
+import { applyDnsRecordTags, claimDnsRecord, defaultDnsComment, resolveRecordFqdn, resolveTtl } from "./dnsRecordBase.js";
 export class ARecord extends Construct {
     record;
     description;
     fqdn;
     constructor(scope, id, props) {
         super(scope, id);
-        this.fqdn = resolveFqdn(props.zoneName, props.recordName);
+        this.fqdn = resolveRecordFqdn(props.recordName, props.zoneName);
         this.description = props.description ?? defaultDnsComment("A", this.fqdn);
+        claimDnsRecord(this, props, "A", this.fqdn);
         this.record = new CdkARecord(this, "Record", {
             zone: props.zone,
             recordName: this.fqdn,

package/dist/lib/resources/aws/networking/dnsRecord/aaaaRecord.js

@@ -1,15 +1,16 @@
 import { Construct } from "constructs";
 import { AaaaRecord as CdkAaaaRecord, RecordTarget } from "aws-cdk-lib/aws-route53";
-import { applyDnsRecordTags, defaultDnsComment, resolveFqdn, resolveTtl } from "./dnsRecordBase.js";
+import { applyDnsRecordTags, claimDnsRecord, defaultDnsComment, resolveRecordFqdn, resolveTtl } from "./dnsRecordBase.js";
 export class AaaaRecord extends Construct {
     record;
     description;
     fqdn;
     constructor(scope, id, props) {
         super(scope, id);
-        this.fqdn = resolveFqdn(props.zoneName, props.recordName);
+        this.fqdn = resolveRecordFqdn(props.recordName, props.zoneName);
         this.description =
             props.description ?? defaultDnsComment("AAAA", this.fqdn);
+        claimDnsRecord(this, props, "AAAA", this.fqdn);
         this.record = new CdkAaaaRecord(this, "Record", {
             zone: props.zone,
             recordName: this.fqdn,

package/dist/lib/resources/aws/networking/dnsRecord/aliasRecord.d.ts

@@ -1,8 +1,30 @@
 import { Construct } from "constructs";
-import { ARecord as CdkARecord, type IAliasRecordTarget } from "aws-cdk-lib/aws-route53";
+import { ARecord as CdkARecord, type GeoLocation, type IAliasRecordTarget } from "aws-cdk-lib/aws-route53";
 import { type DnsRecordCommonProps } from "./dnsRecordBase.js";
 export interface AliasRecordProps extends DnsRecordCommonProps {
     readonly target: IAliasRecordTarget;
+    /**
+     * Latency routing region (CDK `RecordSetOptions.region`). Route53 requires
+     * a `setIdentifier` alongside it — callers derive one when unset.
+     */
+    readonly region?: string;
+    /** Weighted routing weight, 0-255 (CDK `RecordSetOptions.weight`). */
+    readonly weight?: number;
+    /** Geolocation routing (CDK `RecordSetOptions.geoLocation`). */
+    readonly geoLocation?: GeoLocation;
+    /**
+     * Routing-policy record discriminator — distinguishes records that share a
+     * (name, type) pair under latency/weighted/geolocation policies.
+     */
+    readonly setIdentifier?: string;
+    /**
+     * Omit the Route53 record comment entirely. Used for no-churn adoption of
+     * records that pre-date this wrapper (flipless-retain-flip principle: the
+     * default comment would otherwise be a property delta against the live
+     * record's pinned template). The wrapper-level `description` getter is
+     * unaffected.
+     */
+    readonly omitComment?: boolean;
 }
 export declare class AliasRecord extends Construct {
     readonly record: CdkARecord;

package/dist/lib/resources/aws/networking/dnsRecord/aliasRecord.js

@@ -1,22 +1,33 @@
 import { Construct } from "constructs";
 import { ARecord as CdkARecord, RecordTarget } from "aws-cdk-lib/aws-route53";
-import { applyDnsRecordTags, defaultDnsComment, resolveFqdn } from "./dnsRecordBase.js";
+import { applyDnsRecordTags, claimDnsRecord, defaultDnsComment, resolveRecordFqdn } from "./dnsRecordBase.js";
 export class AliasRecord extends Construct {
     record;
     description;
     fqdn;
     constructor(scope, id, props) {
         super(scope, id);
-        this.fqdn = resolveFqdn(props.zoneName, props.recordName);
+        this.fqdn = resolveRecordFqdn(props.recordName, props.zoneName);
         this.description =
             props.description ?? defaultDnsComment("alias", this.fqdn);
+        // An alias record IS an A record set in Route53 — it claims type "A" so
+        // an alias and a plain A record on the same name collide at synth.
+        claimDnsRecord(this, props, "A", this.fqdn);
         // Route53 ignores TTL on ALIAS records — the target dictates caching behaviour,
         // so we deliberately do not forward props.ttl to the underlying CDK resource.
         this.record = new CdkARecord(this, "Record", {
             zone: props.zone,
             recordName: this.fqdn,
             target: RecordTarget.fromAlias(props.target),
-            comment: this.description
+            ...(props.omitComment !== true && { comment: this.description }),
+            ...(props.region !== undefined && { region: props.region }),
+            ...(props.weight !== undefined && { weight: props.weight }),
+            ...(props.geoLocation !== undefined && {
+                geoLocation: props.geoLocation
+            }),
+            ...(props.setIdentifier !== undefined && {
+                setIdentifier: props.setIdentifier
+            })
         });
         applyDnsRecordTags(this, props);
     }

package/dist/lib/resources/aws/networking/dnsRecord/caaRecord.js

@@ -1,14 +1,15 @@
 import { Construct } from "constructs";
 import { CaaRecord as CdkCaaRecord } from "aws-cdk-lib/aws-route53";
-import { applyDnsRecordTags, defaultDnsComment, resolveFqdn, resolveTtl } from "./dnsRecordBase.js";
+import { applyDnsRecordTags, claimDnsRecord, defaultDnsComment, resolveRecordFqdn, resolveTtl } from "./dnsRecordBase.js";
 export class CaaRecord extends Construct {
     record;
     description;
     fqdn;
     constructor(scope, id, props) {
         super(scope, id);
-        this.fqdn = resolveFqdn(props.zoneName, props.recordName);
+        this.fqdn = resolveRecordFqdn(props.recordName, props.zoneName);
         this.description = props.description ?? defaultDnsComment("CAA", this.fqdn);
+        claimDnsRecord(this, props, "CAA", this.fqdn);
         this.record = new CdkCaaRecord(this, "Record", {
             zone: props.zone,
             recordName: this.fqdn,