@fjall/components-infrastructure 14.2.0 → 14.3.0

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

@@ -8,9 +8,9 @@ import { LoadBalancerTarget } from "aws-cdk-lib/aws-route53-targets";
 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, readInjectedManagedDomainCoverage } from "../../../utils/managedDomainContext.js";
-import { computeListenerDefault404 } from "./ingressProfile.js";
+import { isManagedDomainBinding, isWithinZone, recordLabelWithin } from "../../../utils/domainTypes.js";
+import { readInjectedManagedDomainCoverage, resolveEffectiveManagedDomain } from "../../../utils/managedDomainContext.js";
+import { computeListenerDefault404, planListenerRules } from "./ingressProfile.js";
 import { ResourceNaming } from "../../../utils/resourceNaming.js";
 import { stackScopedExportName } from "../../../utils/exportNaming.js";
 import { registerAlbAliasTarget } from "../../../utils/albAliasTargetRegistry.js";
@@ -182,12 +182,6 @@ function preWrapperLogicalId(scope, id) {
         .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;
@@ -198,31 +192,25 @@ export function addHostedZone(ctx, loadBalancer) {
     let hostedZone;
     let zoneName;
     let certificate;
-    // 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));
+    // D2 — the shared precedence and zone-id branch live in
+    // resolveEffectiveManagedDomain (explicit beats injected; binding literal
+    // beats exports Fn.importValue). Bare-CDK synth has no context entry.
+    const effectiveManaged = resolveEffectiveManagedDomain(ctx.scope.node, domainConfig?.managedDomain, domainName, `Cluster '${props.clusterName}'`);
+    const managed = effectiveManaged?.managed;
+    if (effectiveManaged !== undefined && managed !== undefined) {
+        zoneName = effectiveManaged.zoneName;
+        hostedZone = AWSHostedZone.fromHostedZoneAttributes(ctx.scope, `${props.clusterName}ManagedHostedZone`, {
+            hostedZoneId: effectiveManaged.hostedZoneId,
+            zoneName: effectiveManaged.zoneName
+        });
+        // The regional-certificate lane stays per-form: a binding may omit the
+        // ARN (no regional certificate declared), the exports form always
+        // imports it.
+        const certificateArn = isManagedDomainBinding(managed)
+            ? managed.certificateArn
+            : Fn.importValue(managed.certificateArnExport);
+        if (certificateArn !== undefined) {
+            certificate = Certificate.fromCertificateArn(ctx.scope, `${props.clusterName}ManagedCertificate`, certificateArn);
         }
     }
     else if (domainConfig?.hostedZone) {
@@ -328,30 +316,31 @@ export function addHostedZone(ctx, loadBalancer) {
             exportCertificateArn: false
         }).certificate;
     }
-    const additionalListenerCertificates = resolveAdditionalListenerCertificates(ctx.scope, props.clusterName, domainConfig?.additionalCertificates, managed);
-    // D5 certificate coverage (design 2026-08-18 cdn-app-origin): fold the SAN
-    // set of every certificate the listener will carry, where knowable at
-    // synth. The cluster-minted certificate's set is the literal minted above;
-    // managed certificates are described by the CLI-injected coverage context
-    // (absent → opaque, a domain stack predating the hosts outputs); BYO
-    // imports are opaque by nature. Fail-open to "partial"/"unknown", never to
-    // a false "covered" — consumers (the Cdn origin lane) error only on
-    // enumerated non-coverage and warn on opacity.
-    //
-    // Provenance gate: the coverage context describes the zone's CURRENT
-    // certificates — the same D2 resolution that produces an injected binding.
-    // An EXPLICIT `domainConfig.managedDomain` BINDING may pin an OLDER
-    // certificateArn (or usEast1CertificateArn) the current coverage does not
-    // describe, so folding it would over-claim and invert P3 (TLS fails at
-    // runtime after E6 passes the hostname as covered). Explicit bindings
-    // therefore stay opaque, exactly as if no coverage context existed. The
+    // D5 provenance gate (design 2026-08-18 cdn-app-origin): the coverage
+    // context describes the zone's CURRENT certificates — the same D2
+    // resolution that produces an injected binding. An EXPLICIT pinned BINDING
+    // may name OLDER ARNs the current coverage does not describe, so folding
+    // it would over-claim and invert P3 (TLS fails at runtime after E6 passes
+    // the hostname as covered); it stays opaque, exactly as if no coverage
+    // context existed (see EffectiveManagedDomain.explicitPinnedBinding). The
     // explicit EXPORTS form is unaffected: Fn.importValue resolves at deploy
     // to the zone's current certificate — the one the coverage describes.
-    const explicitPinnedBinding = domainConfig?.managedDomain !== undefined &&
-        isManagedDomainBinding(domainConfig.managedDomain);
-    const injectedCoverage = managed && !explicitPinnedBinding
-        ? readInjectedManagedDomainCoverage(ctx.scope.node, managed.zoneName, `Cluster '${props.clusterName}'`)
+    const injectedCoverage = effectiveManaged !== undefined && !effectiveManaged.explicitPinnedBinding
+        ? readInjectedManagedDomainCoverage(ctx.scope.node, effectiveManaged.zoneName, `Cluster '${props.clusterName}'`)
         : undefined;
+    // One walk over the additional-certificate sources yields both the
+    // listener attachments and their coverage facts — the fold below never
+    // re-discriminates the source list.
+    const additional = resolveAdditionalListenerCertificates(ctx.scope, props.clusterName, domainConfig?.additionalCertificates, managed, injectedCoverage?.usEast1CertificateHosts);
+    const additionalListenerCertificates = additional.certificates;
+    // D5 certificate coverage: fold the SAN set of every certificate the
+    // listener will carry, where knowable at synth. The cluster-minted
+    // certificate's set is the literal minted above; managed certificates are
+    // described by the CLI-injected coverage context (absent → opaque, a
+    // domain stack predating the hosts outputs); BYO imports are opaque by
+    // nature. Fail-open to "partial"/"unknown", never to a false "covered" —
+    // consumers (the Cdn origin lane) error only on enumerated non-coverage
+    // and warn on opacity.
     const knownCertificateHosts = [];
     let anyOpaqueCertificate = false;
     if (domainConfig?.certificate) {
@@ -368,17 +357,8 @@ export function addHostedZone(ctx, loadBalancer) {
     else {
         knownCertificateHosts.push(domainName, ...subjectAlternativeNames);
     }
-    for (const source of domainConfig?.additionalCertificates ?? []) {
-        if ("certificateArn" in source) {
-            anyOpaqueCertificate = true;
-        }
-        else if (injectedCoverage?.usEast1CertificateHosts !== undefined) {
-            knownCertificateHosts.push(...injectedCoverage.usEast1CertificateHosts);
-        }
-        else {
-            anyOpaqueCertificate = true;
-        }
-    }
+    knownCertificateHosts.push(...additional.knownHosts);
+    anyOpaqueCertificate = anyOpaqueCertificate || additional.anyOpaque;
     const dedupedCertificateHosts = [...new Set(knownCertificateHosts)];
     const certificateCoverage = anyOpaqueCertificate
         ? dedupedCertificateHosts.length > 0
@@ -503,13 +483,18 @@ const US_EAST_1 = "us-east-1";
  * anything else fails at synth rather than as CloudFormation's opaque
  * deploy-time rejection.
  */
-function resolveAdditionalListenerCertificates(scope, clusterName, sources, managed) {
-    if (sources === undefined || sources.length === 0)
-        return [];
+function resolveAdditionalListenerCertificates(scope, clusterName, sources, managed, usEast1CertificateHosts) {
     const certificates = [];
+    const knownHosts = [];
+    let anyOpaque = false;
+    if (sources === undefined || sources.length === 0) {
+        return { certificates, knownHosts, anyOpaque };
+    }
     for (const source of sources) {
         if ("certificateArn" in source) {
+            // BYO import — opaque by nature.
             certificates.push(ListenerCertificate.fromArn(source.certificateArn));
+            anyOpaque = true;
             continue;
         }
         if (managed === undefined ||
@@ -543,8 +528,16 @@ function resolveAdditionalListenerCertificates(scope, clusterName, sources, mana
                 "stack, or supply certificateArn for a same-region certificate.");
         }
         certificates.push(ListenerCertificate.fromArn(arn));
+        // The managed us-east-1 certificate's hosts, when the coverage context
+        // describes them (absent → a domain stack predating the hosts outputs).
+        if (usEast1CertificateHosts !== undefined) {
+            knownHosts.push(...usEast1CertificateHosts);
+        }
+        else {
+            anyOpaque = true;
+        }
     }
-    return certificates;
+    return { certificates, knownHosts, anyOpaque };
 }
 export function addDirectAccessOutputs(ctx, autoScalingGroup) {
     if (!ctx.directAccessEnabled || !autoScalingGroup)
@@ -567,15 +560,17 @@ export function addDirectAccessOutputs(ctx, autoScalingGroup) {
 }
 export function registerServiceWithALB(ctx, listener, serviceName, serviceProps, service, primaryContainer, priorityState) {
     const containerPort = primaryContainer.containerPort;
-    // Normalise routing to array
-    const routingRules = Array.isArray(serviceProps.routing)
-        ? serviceProps.routing
-        : serviceProps.routing
-            ? [serviceProps.routing]
-            : [];
+    // The single home of the listener branching (P5, ingressProfile.ts): the
+    // ingress profile's rule model derives from this same plan, so what the
+    // profile reports is what this emitter builds.
+    const servicePlan = planListenerRules(ctx.props.services, []).services.find((plan) => plan.service === serviceProps);
+    if (servicePlan === undefined) {
+        throw new Error(`Service '${serviceName}' is not in the listener rule plan — ` +
+            "registerServiceWithALB was called for a service with no container " +
+            "ports, which can never receive listener traffic.");
+    }
+    const { routingRules } = servicePlan;
     const healthCheckPath = routingRules.find((r) => r.healthCheckPath)?.healthCheckPath ?? "/";
-    const servicesWithPorts = ctx.props.services.filter((s) => s.containers.some((c) => c.port !== undefined));
-    const isSingleService = servicesWithPorts.length === 1;
     const healthCheckConfig = isServiceEc2(serviceProps)
         ? {
             interval: Duration.seconds(30),
@@ -591,7 +586,7 @@ export function registerServiceWithALB(ctx, listener, serviceName, serviceProps,
             port: `${containerPort}`,
             timeout: Duration.seconds(10)
         };
-    if (isSingleService && routingRules.length <= 1) {
+    if (servicePlan.mode === "default") {
         return listener.addTargets(`${serviceName}TargetGroup`, {
             targets: [
                 service.loadBalancerTarget({

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

@@ -9,14 +9,15 @@
  * P5 (model the machinery, don't paraphrase it): every fact here is exported
  * from the SAME computation the emitting code uses — `default404` is the
  * predicate `addLoadBalancerListener` passes to the listener factory, the
- * rule structure mirrors `registerServiceWithALB`'s exact branching
- * (including the single-service conditions-dropped branch), and the covered
- * SAN set is the one `addHostedZone` mints. Never recompute these facts from
- * cluster props elsewhere; extend the profile instead.
+ * rule structure derives from the `planListenerRules` plan that
+ * `registerServiceWithALB` itself emits from (including the single-service
+ * conditions-dropped branch), and the covered SAN set is the one
+ * `addHostedZone` mints. Never recompute these facts from cluster props
+ * elsewhere; extend the plan or the profile instead.
  */
 import type { IApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalancingv2";
 import type { IHostedZone } from "aws-cdk-lib/aws-route53";
-import type { EcsServiceProps } from "./ecsTypes.js";
+import type { EcsRoutingConfig, EcsServiceProps } from "./ecsTypes.js";
 /**
  * What the certificates ATTACHED to the cluster's listener are known to
  * cover at synth:
@@ -96,20 +97,48 @@ export interface EcsIngressZoneFacts {
     certificateCoverage: CertificateCoverage;
 }
 /**
- * The listener's default-action predicate — the SINGLE home of the
- * computation `addLoadBalancerListener` passes to the listener factory as
- * `default404`. `true` when ≥2 routes will exist (the emitter then attaches
- * a fixed-404 default and conditions every rule) or when no service has a
- * port (CDK rejects a listener with neither a default action nor targets).
+ * One ports-bearing service's listener treatment. `mode: "default"` — the
+ * sole ports-bearing service with ≤1 routing rule: its target group is
+ * added UNCONDITIONED and becomes the listener default action (even a
+ * declared `routing.host` does not gate it). `mode: "rules"` — every
+ * routing rule becomes a conditioned, prioritised listener rule; the first
+ * carries the target group.
+ */
+export interface ListenerServicePlan {
+    service: EcsServiceProps;
+    /** The service's `routing` config, normalised to an array. */
+    routingRules: EcsRoutingConfig[];
+    mode: "default" | "rules";
+}
+export interface ListenerRulePlan {
+    /** Ports-bearing services in declaration order (portless services never
+     * reach the listener). */
+    services: ListenerServicePlan[];
+    redirectHosts: string[];
+}
+/**
+ * The listener's rule structure, planned once (P5). This is the SINGLE home
+ * of the branching: `registerServiceWithALB` emits from a service's plan
+ * entry, and the ingress-profile facts below (`computeListenerDefault404`,
+ * `enumerateListenerRules`) derive from the same plan — the emitter and the
+ * model cannot drift because neither re-derives the decisions.
+ */
+export declare function planListenerRules(services: EcsServiceProps[], redirectHosts: string[]): ListenerRulePlan;
+/**
+ * The listener's default-action predicate — the value
+ * `addLoadBalancerListener` passes to the listener factory as `default404`.
+ * `true` exactly when no service plan supplies an unconditioned default
+ * target group: ≥2 routes will exist (the emitter then attaches a fixed-404
+ * default and conditions every rule), or no service has a port (CDK rejects
+ * a listener with neither a default action nor targets).
  */
 export declare function computeListenerDefault404(services: EcsServiceProps[]): boolean;
 /**
  * The listener's rule structure as `registerServiceWithALB` and
- * `addRedirectHostRules` will emit it. Mirrors the emitters' branching
- * exactly: a single ports-bearing service with ≤1 rule contributes NO
- * conditioned rule (its target group is the listener default — even a
- * declared `routing.host` does not gate it), and every redirect host
- * contributes a host-matched 301 rule.
+ * `addRedirectHostRules` will emit it — derived from the same
+ * `planListenerRules` plan the emitters consume: a `mode: "default"`
+ * service contributes NO conditioned rule (its target group is the listener
+ * default), and every redirect host contributes a host-matched 301 rule.
  */
 export declare function enumerateListenerRules(services: EcsServiceProps[], redirectHosts: string[]): EcsIngressRule[];
 /** Lowercase and strip the trailing dot — DNS names are case-insensitive. */

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

@@ -9,10 +9,11 @@
  * P5 (model the machinery, don't paraphrase it): every fact here is exported
  * from the SAME computation the emitting code uses — `default404` is the
  * predicate `addLoadBalancerListener` passes to the listener factory, the
- * rule structure mirrors `registerServiceWithALB`'s exact branching
- * (including the single-service conditions-dropped branch), and the covered
- * SAN set is the one `addHostedZone` mints. Never recompute these facts from
- * cluster props elsewhere; extend the profile instead.
+ * rule structure derives from the `planListenerRules` plan that
+ * `registerServiceWithALB` itself emits from (including the single-service
+ * conditions-dropped branch), and the covered SAN set is the one
+ * `addHostedZone` mints. Never recompute these facts from cluster props
+ * elsewhere; extend the plan or the profile instead.
  */
 import { FjallLogger } from "../../../utils/validationLogger.js";
 function normaliseRoutingRules(routing) {
@@ -22,35 +23,54 @@ function servicesWithPorts(services) {
     return services.filter((s) => s.containers.some((c) => c.port !== undefined));
 }
 /**
- * The listener's default-action predicate — the SINGLE home of the
- * computation `addLoadBalancerListener` passes to the listener factory as
- * `default404`. `true` when ≥2 routes will exist (the emitter then attaches
- * a fixed-404 default and conditions every rule) or when no service has a
- * port (CDK rejects a listener with neither a default action nor targets).
+ * The listener's rule structure, planned once (P5). This is the SINGLE home
+ * of the branching: `registerServiceWithALB` emits from a service's plan
+ * entry, and the ingress-profile facts below (`computeListenerDefault404`,
+ * `enumerateListenerRules`) derive from the same plan — the emitter and the
+ * model cannot drift because neither re-derives the decisions.
  */
-export function computeListenerDefault404(services) {
+export function planListenerRules(services, redirectHosts) {
     const withPorts = servicesWithPorts(services);
-    const willHaveMultipleRoutes = withPorts.length > 1 ||
-        withPorts.some((s) => normaliseRoutingRules(s.routing).length > 1);
-    return willHaveMultipleRoutes || withPorts.length === 0;
+    const isSingleService = withPorts.length === 1;
+    return {
+        services: withPorts.map((service) => {
+            const routingRules = normaliseRoutingRules(service.routing);
+            return {
+                service,
+                routingRules,
+                mode: isSingleService && routingRules.length <= 1
+                    ? "default"
+                    : "rules"
+            };
+        }),
+        redirectHosts
+    };
+}
+/**
+ * The listener's default-action predicate — the value
+ * `addLoadBalancerListener` passes to the listener factory as `default404`.
+ * `true` exactly when no service plan supplies an unconditioned default
+ * target group: ≥2 routes will exist (the emitter then attaches a fixed-404
+ * default and conditions every rule), or no service has a port (CDK rejects
+ * a listener with neither a default action nor targets).
+ */
+export function computeListenerDefault404(services) {
+    return !planListenerRules(services, []).services.some((plan) => plan.mode === "default");
 }
 /**
  * The listener's rule structure as `registerServiceWithALB` and
- * `addRedirectHostRules` will emit it. Mirrors the emitters' branching
- * exactly: a single ports-bearing service with ≤1 rule contributes NO
- * conditioned rule (its target group is the listener default — even a
- * declared `routing.host` does not gate it), and every redirect host
- * contributes a host-matched 301 rule.
+ * `addRedirectHostRules` will emit it — derived from the same
+ * `planListenerRules` plan the emitters consume: a `mode: "default"`
+ * service contributes NO conditioned rule (its target group is the listener
+ * default), and every redirect host contributes a host-matched 301 rule.
  */
 export function enumerateListenerRules(services, redirectHosts) {
-    const withPorts = servicesWithPorts(services);
-    const isSingleService = withPorts.length === 1;
+    const plan = planListenerRules(services, redirectHosts);
     const rules = [];
-    for (const service of withPorts) {
-        const routingRules = normaliseRoutingRules(service.routing);
-        if (isSingleService && routingRules.length <= 1)
+    for (const servicePlan of plan.services) {
+        if (servicePlan.mode === "default")
             continue;
-        for (const rule of routingRules) {
+        for (const rule of servicePlan.routingRules) {
             if (rule.host === undefined && rule.path === undefined)
                 continue;
             rules.push({
@@ -60,7 +80,7 @@ export function enumerateListenerRules(services, redirectHosts) {
             });
         }
     }
-    for (const host of redirectHosts) {
+    for (const host of plan.redirectHosts) {
         rules.push({ host, kind: "redirect" });
     }
     return rules;

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

@@ -1,8 +1,16 @@
 import { Construct } from "constructs";
-import { ARecord as CdkARecord, type GeoLocation, type IAliasRecordTarget } from "aws-cdk-lib/aws-route53";
+import { ARecord as CdkARecord, AaaaRecord as CdkAaaaRecord, type GeoLocation, type IAliasRecordTarget } from "aws-cdk-lib/aws-route53";
 import { type DnsRecordCommonProps } from "./dnsRecordBase.js";
 export interface AliasRecordProps extends DnsRecordCommonProps {
     readonly target: IAliasRecordTarget;
+    /**
+     * Record-set type the alias deploys as: `"A"` (IPv4, the default — every
+     * pattern-internal alias predates this knob and is a deployed A record)
+     * or `"AAAA"` (IPv6). A declared AAAA alias MUST deploy as AAAA — mapping
+     * it to A silently answers IPv4 for an IPv6 declaration and collides with
+     * a legal dual-stack sibling in the DNS claim registry.
+     */
+    readonly recordType?: "A" | "AAAA";
     /**
      * Latency routing region (CDK `RecordSetOptions.region`). Route53 requires
      * a `setIdentifier` alongside it — callers derive one when unset.
@@ -27,7 +35,7 @@ export interface AliasRecordProps extends DnsRecordCommonProps {
     readonly omitComment?: boolean;
 }
 export declare class AliasRecord extends Construct {
-    readonly record: CdkARecord;
+    readonly record: CdkARecord | CdkAaaaRecord;
     readonly description: string;
     readonly fqdn: string;
     constructor(scope: Construct, id: string, props: AliasRecordProps);

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

@@ -1,5 +1,5 @@
 import { Construct } from "constructs";
-import { ARecord as CdkARecord, RecordTarget } from "aws-cdk-lib/aws-route53";
+import { ARecord as CdkARecord, AaaaRecord as CdkAaaaRecord, RecordTarget } from "aws-cdk-lib/aws-route53";
 import { applyDnsRecordTags, claimDnsRecord, defaultDnsComment, resolveRecordFqdn } from "./dnsRecordBase.js";
 export class AliasRecord extends Construct {
     record;
@@ -7,14 +7,17 @@ export class AliasRecord extends Construct {
     fqdn;
     constructor(scope, id, props) {
         super(scope, id);
+        const recordType = props.recordType ?? "A";
         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. The
-        // routing variant rides along: policy siblings with distinct
-        // setIdentifiers (e.g. a compute apex alias and a CDN apex alias during
-        // an ingress migration) are legal and register cleanly.
+        // An alias record IS an A (or AAAA) record set in Route53 — it claims
+        // its deployed type so an alias and a plain record of that type on the
+        // same name collide at synth, while dual-stack A + AAAA siblings
+        // register cleanly. The routing variant rides along: policy siblings
+        // with distinct setIdentifiers (e.g. a compute apex alias and a CDN
+        // apex alias during an ingress migration) are legal and register
+        // cleanly.
         const routingPolicy = props.region !== undefined
             ? "latency"
             : props.weight !== undefined
@@ -34,7 +37,7 @@ export class AliasRecord extends Construct {
                 .filter((part) => part !== undefined)
                 .join("/") || "*"
             : undefined;
-        claimDnsRecord(this, props, "A", this.fqdn, {
+        claimDnsRecord(this, props, recordType, this.fqdn, {
             setIdentifier: props.setIdentifier,
             routingPolicy,
             region: props.region,
@@ -42,7 +45,9 @@ export class AliasRecord extends Construct {
         });
         // 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", {
+        // Both branches share the "Record" child id: an existing A alias's
+        // logical ID is byte-frozen, and a declared type is the ONLY delta.
+        const recordProps = {
             zone: props.zone,
             recordName: this.fqdn,
             target: RecordTarget.fromAlias(props.target),
@@ -55,7 +60,11 @@ export class AliasRecord extends Construct {
             ...(props.setIdentifier !== undefined && {
                 setIdentifier: props.setIdentifier
             })
-        });
+        };
+        this.record =
+            recordType === "AAAA"
+                ? new CdkAaaaRecord(this, "Record", recordProps)
+                : new CdkARecord(this, "Record", recordProps);
         applyDnsRecordTags(this, props);
     }
 }

package/dist/lib/utils/dnsRecordRegistry.d.ts

@@ -46,11 +46,9 @@ export interface DnsRecordClaim {
      */
     readonly recordType: string;
     /**
-     * Routing-variant discriminator. A claim is a policy variant when it
-     * carries a `routingPolicy` OR a `setIdentifier` (CDK auto-generates a
-     * SetIdentifier for a policy record declared without one, so policy
-     * presence alone makes a legal variant); a claim with neither is a simple
-     * record that tolerates no siblings.
+     * Routing-variant discriminator among sibling variants. Variant-ness
+     * itself is decided by `routingPolicy` alone (see {@link isVariantEntry});
+     * a claim without one is a simple record that tolerates no siblings.
      */
     readonly setIdentifier?: string;
     /** Policy type of a variant claim — siblings must all match. */

package/dist/lib/utils/dnsRecordRegistry.js

@@ -1,15 +1,16 @@
 import { Token } from "aws-cdk-lib";
 /**
- * A claim is a policy variant when it declares a routing policy OR carries a
- * setIdentifier: CDK's RecordSet auto-generates a SetIdentifier whenever a
- * policy (region/weight/geoLocation) is set without one, so a policy claim
- * with no explicit setIdentifier still deploys as a legal sibling variant —
- * classifying it as simple would refuse shapes Route53 holds happily.
- * (A setIdentifier WITHOUT a policy cannot deploy — CDK rejects it at synth —
- * so its classification here never decides a real outcome.)
+ * A claim is a policy variant exactly when it declares a routing policy:
+ * CDK's RecordSet auto-generates a SetIdentifier whenever a policy
+ * (region/weight/geoLocation) is set without one, so a policy claim with no
+ * explicit setIdentifier still deploys as a legal sibling variant —
+ * classifying it as simple would refuse shapes Route53 holds happily. A
+ * setIdentifier WITHOUT a policy cannot deploy at all (CDK rejects it at
+ * synth), so it classifies as simple and the simple-vs-variant refusal —
+ * whose cure names the missing routing policy — fires first.
  */
 function isVariantEntry(entry) {
-    return entry.routingPolicy !== undefined || entry.setIdentifier !== undefined;
+    return entry.routingPolicy !== undefined;
 }
 /** Claims per App root: claim key → claimant entries (variants share a key). */
 let claimsByRoot = new WeakMap();
@@ -87,12 +88,8 @@ export function registerDnsRecordClaim(scope, claim) {
             other.setIdentifier === entry.setIdentifier) {
             throw collisionError(claim, recordType, other, claimantPath, `Both records carry setIdentifier '${String(entry.setIdentifier)}' — sibling routing-policy variants need distinct setIdentifiers.`);
         }
-        // Policy types compare only when both are declared: a setIdentifier-only
-        // claim carries no policy for Route53 to mismatch (and cannot deploy —
-        // CDK rejects setIdentifier on simple records at synth).
-        if (other.routingPolicy !== undefined &&
-            entry.routingPolicy !== undefined &&
-            other.routingPolicy !== entry.routingPolicy) {
+        // Both sides passed isVariantEntry, so both declare a policy.
+        if (other.routingPolicy !== entry.routingPolicy) {
             throw collisionError(claim, recordType, other, claimantPath, `Sibling routing-policy variants must share one policy type (got '${String(other.routingPolicy)}' vs '${String(entry.routingPolicy)}') — Route53 rejects mixed-policy siblings.`);
         }
         if (entry.routingPolicy === "latency" &&

package/dist/lib/utils/domainTypes.d.ts

@@ -8,6 +8,17 @@ export { DNS_APEX, getDomainExportNames, isManagedDomainBinding, type ManagedDom
  * § Infrastructure Layer Boundaries).
  */
 export declare function isWithinZone(candidate: string, zoneName: string): boolean;
+/**
+ * Relative record label for `domain` within `zoneName` — the inverse of
+ * `resolveRecordFqdn` for names already known to sit inside the zone: the
+ * zone apex maps to the canonical apex label, sub-names drop the zone
+ * suffix. A name outside the zone passes through unchanged (callers
+ * validate zone membership with `isWithinZone` first). Single home shared
+ * by the patterns-layer CDN origin lane and the resources-layer ECS
+ * networking (lowest common layer per generator-standards § Infrastructure
+ * Layer Boundaries).
+ */
+export declare function recordLabelWithin(domain: string, zoneName: string): string;
 /**
  * Canonical BIND-semantics resolver for DNS record names — the single
  * authority shared by the patterns-layer domain validation and the

package/dist/lib/utils/domainTypes.js

@@ -14,6 +14,23 @@ export function isWithinZone(candidate, zoneName) {
     }
     return candidate.endsWith(`.${zoneName}`);
 }
+/**
+ * Relative record label for `domain` within `zoneName` — the inverse of
+ * `resolveRecordFqdn` for names already known to sit inside the zone: the
+ * zone apex maps to the canonical apex label, sub-names drop the zone
+ * suffix. A name outside the zone passes through unchanged (callers
+ * validate zone membership with `isWithinZone` first). Single home shared
+ * by the patterns-layer CDN origin lane and the resources-layer ECS
+ * networking (lowest common layer per generator-standards § Infrastructure
+ * Layer Boundaries).
+ */
+export function recordLabelWithin(domain, zoneName) {
+    if (domain === zoneName) {
+        return DNS_APEX;
+    }
+    const suffix = `.${zoneName}`;
+    return domain.endsWith(suffix) ? domain.slice(0, -suffix.length) : domain;
+}
 /**
  * Canonical BIND-semantics resolver for DNS record names — the single
  * authority shared by the patterns-layer domain validation and the