@fjall/components-infrastructure 14.0.0 → 14.1.0

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

@@ -6,9 +6,50 @@ import { type ICachePolicy, type IResponseHeadersPolicy } from "aws-cdk-lib/aws-
 import type App from "../../app.js";
 import { CloudFrontDistribution, type CachePolicyPreset, type AccessGateConfig } from "../../resources/aws/cdn/index.js";
 import { type ICdn } from "./interfaces/cdn.js";
-import type { StaticSiteRouting } from "@fjall/util";
+import { type StaticSiteRouting } from "@fjall/util";
+import { type ManagedDomainBinding, type ManagedDomainExports } from "../../utils/domainTypes.js";
 import { type Storage } from "./storage.js";
 import { type AnyCompute } from "./compute.js";
+/**
+ * Managed-domain surface for a CDN — the distribution's counterpart to the
+ * ECS cluster's `domainConfig` (design 2026-08-17 cdn-domain-ownership C1).
+ * The CDN resolves its zone and us-east-1 viewer certificate exactly like
+ * the staticSite/payload patterns (explicit `managedDomain` beats the
+ * CLI-injected binding, which beats BYO `zoneName`/`hostedZoneId`), derives
+ * `domainNames` from `domainName`, and — unless `record: "none"` — owns the
+ * alias record for it in the CDN stack, satellite-style.
+ */
+export interface CdnDomainConfig {
+    /** Public hostname the distribution serves, e.g. the zone apex. */
+    domainName: string;
+    /**
+     * "alias" (default) mints the Route53 alias record in the CDN stack.
+     * "none" claims the alternate domain name + certificate WITHOUT the DNS
+     * record — the pre-flip validation state: the distribution answers for
+     * `domainName` (testable via `curl --resolve`) while live DNS still points
+     * elsewhere.
+     */
+    record?: "alias" | "none";
+    /**
+     * Routing policy for the alias record. Use latency with a region label
+     * DIFFERENT from an existing compute-owned variant on the same name —
+     * Route53 allows one latency record per region, and sibling variants are
+     * exactly how an apex migrates between owners with no delete window (the
+     * claim registry enforces the legal shapes).
+     */
+    routingPolicy?: {
+        type: "latency";
+        region: string;
+    };
+    /** Defaults to `${id}${region}` when `routingPolicy` is set — the same
+     * derivation convention as the ECS cluster's apex record. */
+    setIdentifier?: string;
+    /** Explicit managed-domain identity — beats the CLI-injected binding. */
+    managedDomain?: ManagedDomainExports | ManagedDomainBinding;
+    /** BYO zone identity (with `hostedZoneId` to skip the runtime lookup). */
+    zoneName?: string;
+    hostedZoneId?: string;
+}
 /**
  * Common CDN props shared across all origin types.
  */
@@ -19,6 +60,20 @@ interface BaseCdnProps {
      * is only set by hand for a directly-instantiated `Cdn`.
      */
     appName?: string;
+    /**
+     * Managed-domain surface: resolve the zone + us-east-1 viewer certificate
+     * through the domain helpers and own the domain's alias record in the CDN
+     * stack. Mutually exclusive with the literal
+     * `domainNames`/`certificate`/`certificateArn` surface, and requires the
+     * factory path (`app.addCdn(CdnFactory.build(...))`) so the `App` is known.
+     */
+    domainConfig?: CdnDomainConfig;
+    /**
+     * App instance backing `domainConfig` resolution (certificate placement,
+     * zone lookups). `CdnFactory.build` fills it — only set by hand for a
+     * directly-instantiated `Cdn`.
+     */
+    app?: App;
     cachePolicy?: CachePolicyPreset | ICachePolicy;
     defaultAllowedMethods?: "GET_HEAD" | "GET_HEAD_OPTIONS" | "ALL";
     behaviours?: SmartCdnBehaviour[];
@@ -97,6 +152,24 @@ export interface SmartCdnBehaviour {
  */
 export declare class Cdn extends CloudFrontDistribution implements ICdn {
     constructor(scope: Construct, id: string, props: ICdnProps);
+    /**
+     * Resolve a `domainConfig` through the shared pattern-domain helpers
+     * (design C1): zone identity via `resolvePatternZone` (explicit
+     * `managedDomain` → CLI-injected binding → BYO `zoneName`/`hostedZoneId`),
+     * viewer certificate via `resolvePatternCloudFrontCertificate` (binding's
+     * literal us-east-1 ARN, else app-owned provisioning). The exact resolution
+     * chain staticSite and payload already use — the CDN stops being the one
+     * CloudFront-fronted pattern without it.
+     */
+    private static resolveDomain;
+    /**
+     * Own the domain's DNS record in the CDN stack (satellite doctrine — the
+     * app owns its records, the domain stack owns zone-level records), exactly
+     * as the ECS cluster owns its apex alias. Latency routing gets the
+     * cluster's setIdentifier derivation (`${id}${region}`) unless overridden;
+     * `record: "none"` skips this entirely (pre-flip validation state).
+     */
+    private createDomainRecord;
     /**
      * Resolve ICdnProps to CloudFrontDistributionProps.
      */
@@ -148,6 +221,20 @@ export declare class Cdn extends CloudFrontDistribution implements ICdn {
  *   domainNames: ["app.example.com"],
  *   certificate: myCert
  * }));
+ *
+ * @example
+ * // Managed domain — the CDN resolves the zone + us-east-1 certificate and
+ * // owns the alias record in its own stack (satellite doctrine), like the
+ * // ECS cluster's domainConfig.
+ * app.addCdn(CdnFactory.build("AppCdn", {
+ *   originType: "http",
+ *   domainName: "origin.example.com",
+ *   forwardHostHeader: true,
+ *   domainConfig: {
+ *     domainName: "example.com",
+ *     routingPolicy: { type: "latency", region: "us-east-1" }
+ *   }
+ * }));
  */
 export declare class CdnFactory {
     /**

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

@@ -1,14 +1,110 @@
 import { Fn, Token } from "aws-cdk-lib";
 import { Certificate } from "aws-cdk-lib/aws-certificatemanager";
+import { CloudFrontTarget } from "aws-cdk-lib/aws-route53-targets";
 import { CloudFrontDistribution } from "../../resources/aws/cdn/index.js";
+import { AliasRecord } from "../../resources/aws/networking/index.js";
+import { DNS_APEX } from "@fjall/util";
+import { resolvePatternZone, resolvePatternCloudFrontCertificate } from "./patternDomain.js";
 import { isStorage } from "./storage.js";
 import { isCompute, isEcsCompute, isLambdaCompute } from "./compute.js";
+/**
+ * Relative record label for `domain` within `zoneName` (the staticSite
+ * `recordLabelFor` convention): the zone apex maps to the canonical apex
+ * label, sub-names drop the zone suffix.
+ */
+function recordLabelWithin(domain, zoneName) {
+    if (domain === zoneName) {
+        return DNS_APEX;
+    }
+    const suffix = `.${zoneName}`;
+    return domain.endsWith(suffix) ? domain.slice(0, -suffix.length) : domain;
+}
+/** Lowercase and strip the trailing dot — DNS names are case-insensitive. */
+function normaliseDnsName(name) {
+    return name.toLowerCase().replace(/\.$/, "");
+}
 /**
  * Validates CDN props — synth-time hard errors for shapes CloudFormation
  * would only reject at deploy.
  */
 function validateCdnProps(props) {
     const hasCertificate = !!(props.certificate || props.certificateArn);
+    // domainConfig is the managed-domain authority for the viewer config —
+    // mixing it with the literal surface would give the alias list and the
+    // certificate two owners with no defined precedence.
+    if (props.domainConfig !== undefined) {
+        if (props.domainNames !== undefined || hasCertificate) {
+            throw new Error(`CDN 'domainConfig' ('${props.domainConfig.domainName}') cannot be ` +
+                "combined with 'domainNames', 'certificate', or 'certificateArn'. " +
+                "'domainConfig' derives the alternate domain names and resolves " +
+                "the us-east-1 viewer certificate itself — drop the literal props, " +
+                "or drop 'domainConfig' and manage both by hand.");
+        }
+        if (props.app === undefined) {
+            throw new Error(`CDN 'domainConfig' ('${props.domainConfig.domainName}') requires ` +
+                "the App for certificate placement, but 'app' is unset. Create the " +
+                "CDN through the factory path — app.addCdn(CdnFactory.build(...)) " +
+                "— which fills it, or pass 'app' explicitly.");
+        }
+        // Latency region and setIdentifier are literals by contract — inspect
+        // them at synth so a config slip fails here with the cure, not at
+        // CloudFormation with a raw Route53 InvalidChangeBatch (or, for the
+        // empty-string cases, a CDK error about a prop the user never set).
+        const region = props.domainConfig.routingPolicy?.region;
+        if (region !== undefined && !/^[a-z]{2,4}(-[a-z]+)+-\d+$/.test(region)) {
+            throw new Error(`CDN 'domainConfig.routingPolicy.region' ('${region}') is not an ` +
+                "AWS region name (expected e.g. 'us-east-1'). Route53 latency " +
+                "records carry a literal region label — fix the region string.");
+        }
+        const setIdentifier = props.domainConfig.setIdentifier;
+        if (setIdentifier !== undefined &&
+            (setIdentifier.trim() === "" || setIdentifier.length > 128)) {
+            throw new Error(`CDN 'domainConfig.setIdentifier' (${JSON.stringify(setIdentifier)}) ` +
+                "must be 1-128 non-blank characters (Route53 SetIdentifier limit). " +
+                "Omit it to use the derived '<id><region>' value.");
+        }
+    }
+    // Origin-loop guard (design 2026-08-17 cdn-domain-ownership C4): an HTTP
+    // origin pointing at one of the distribution's own domain names sends
+    // every request CloudFront → DNS → CloudFront until the request-depth
+    // limit 508s. Synth can see this shape whenever the origin hostname is a
+    // literal, so refuse it with the cure.
+    const aliasNames = new Set();
+    if (props.domainConfig !== undefined) {
+        aliasNames.add(normaliseDnsName(props.domainConfig.domainName));
+    }
+    for (const name of props.domainNames ?? []) {
+        if (!Token.isUnresolved(name)) {
+            aliasNames.add(normaliseDnsName(name));
+        }
+    }
+    const defaultOriginHostname = props.originType === "http"
+        ? props.domainName
+        : props.originType === "auto" && typeof props.origin === "string"
+            ? props.origin
+            : undefined;
+    // Behaviour origins are the same literal-HTTP-origin surface: a string
+    // behaviour origin becomes an HTTP origin via detectOriginFromResource, so
+    // a self-referential one loops exactly like the default origin — but only
+    // for its path pattern, a PARTIAL outage that is even harder to spot.
+    const literalOriginHostnames = [
+        ...(defaultOriginHostname !== undefined ? [defaultOriginHostname] : []),
+        ...(props.behaviours ?? [])
+            .map((behaviour) => behaviour.origin)
+            .filter((origin) => typeof origin === "string")
+    ];
+    for (const originHostname of literalOriginHostnames) {
+        if (!Token.isUnresolved(originHostname) &&
+            aliasNames.has(normaliseDnsName(originHostname))) {
+            throw new Error(`CDN origin '${originHostname}' is also one of the distribution's own ` +
+                "domain names — once DNS points that name at the distribution, every " +
+                "request loops CloudFront → CloudFront. Point the origin at a " +
+                "dedicated origin hostname instead (e.g. an ECS service " +
+                "'routing[].host' such as 'origin.<zone>' resolving to the load " +
+                "balancer, or a domain-stack record targeting the origin resource) " +
+                "and keep the public name on the CDN.");
+        }
+    }
     // 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
@@ -73,20 +169,80 @@ function validateCdnProps(props) {
 export class Cdn extends CloudFrontDistribution {
     constructor(scope, id, props) {
         validateCdnProps(props);
-        const resolvedProps = Cdn.resolveProps(scope, id, props);
+        // Zone + certificate resolve BEFORE super() — the viewer certificate is
+        // part of the distribution's props — so their constructs land on the CDN
+        // stack (`scope`) under `${id}`-prefixed IDs, the pattern convention.
+        const domain = props.domainConfig !== undefined && props.app !== undefined
+            ? Cdn.resolveDomain(scope, id, props.domainConfig, props.app)
+            : undefined;
+        const resolvedProps = Cdn.resolveProps(scope, id, props, domain);
         super(scope, id, resolvedProps);
+        if (domain !== undefined && props.domainConfig !== undefined) {
+            this.createDomainRecord(id, props.domainConfig, domain);
+        }
+    }
+    /**
+     * Resolve a `domainConfig` through the shared pattern-domain helpers
+     * (design C1): zone identity via `resolvePatternZone` (explicit
+     * `managedDomain` → CLI-injected binding → BYO `zoneName`/`hostedZoneId`),
+     * viewer certificate via `resolvePatternCloudFrontCertificate` (binding's
+     * literal us-east-1 ARN, else app-owned provisioning). The exact resolution
+     * chain staticSite and payload already use — the CDN stops being the one
+     * CloudFront-fronted pattern without it.
+     */
+    static resolveDomain(scope, id, domainConfig, app) {
+        const request = {
+            scope,
+            app,
+            idPrefix: id,
+            context: `CDN '${id}'`,
+            domain: domainConfig.domainName,
+            identity: domainConfig
+        };
+        const zone = resolvePatternZone(request);
+        const certificate = resolvePatternCloudFrontCertificate(request, zone);
+        return { zone, certificate };
+    }
+    /**
+     * Own the domain's DNS record in the CDN stack (satellite doctrine — the
+     * app owns its records, the domain stack owns zone-level records), exactly
+     * as the ECS cluster owns its apex alias. Latency routing gets the
+     * cluster's setIdentifier derivation (`${id}${region}`) unless overridden;
+     * `record: "none"` skips this entirely (pre-flip validation state).
+     */
+    createDomainRecord(id, domainConfig, domain) {
+        if (domainConfig.record === "none") {
+            return;
+        }
+        const region = domainConfig.routingPolicy?.region;
+        const setIdentifier = domainConfig.setIdentifier ??
+            (region !== undefined ? `${id}${region}` : undefined);
+        new AliasRecord(this, "AliasRecord", {
+            zone: domain.zone.hostedZone,
+            zoneName: domain.zone.zoneName,
+            recordName: recordLabelWithin(domainConfig.domainName, domain.zone.zoneName),
+            // CloudFrontTarget sets no EvaluateTargetHealth — Route53 requires it
+            // absent for CloudFront alias targets.
+            target: new CloudFrontTarget(this.getDistribution()),
+            ...(region !== undefined && { region }),
+            ...(setIdentifier !== undefined && { setIdentifier })
+        });
     }
     /**
      * Resolve ICdnProps to CloudFrontDistributionProps.
      */
-    static resolveProps(scope, id, props) {
+    static resolveProps(scope, id, props, domain) {
         const defaultOrigin = Cdn.resolveDefaultOrigin(props);
         const behaviours = Cdn.resolveBehaviours(props.behaviours);
         const appName = props.appName;
+        const domainNames = props.domainNames ??
+            (props.domainConfig !== undefined
+                ? [props.domainConfig.domainName]
+                : undefined);
         const certificate = props.certificate ??
             (props.certificateArn
                 ? Certificate.fromCertificateArn(scope, `${id}Certificate`, props.certificateArn)
-                : undefined);
+                : domain?.certificate);
         const s3Routing = props.originType === "s3"
             ? {
                 defaultRootObject: props.defaultRootObject,
@@ -102,7 +258,7 @@ export class Cdn extends CloudFrontDistribution {
             defaultCachePolicy: props.cachePolicy,
             defaultAllowedMethods: props.defaultAllowedMethods,
             behaviours,
-            domainNames: props.domainNames,
+            domainNames,
             certificate,
             comment: props.comment,
             enableLogging: props.enableLogging,
@@ -265,6 +421,20 @@ export class Cdn extends CloudFrontDistribution {
  *   domainNames: ["app.example.com"],
  *   certificate: myCert
  * }));
+ *
+ * @example
+ * // Managed domain — the CDN resolves the zone + us-east-1 certificate and
+ * // owns the alias record in its own stack (satellite doctrine), like the
+ * // ECS cluster's domainConfig.
+ * app.addCdn(CdnFactory.build("AppCdn", {
+ *   originType: "http",
+ *   domainName: "origin.example.com",
+ *   forwardHostHeader: true,
+ *   domainConfig: {
+ *     domainName: "example.com",
+ *     routingPolicy: { type: "latency", region: "us-east-1" }
+ *   }
+ * }));
  */
 export class CdnFactory {
     /**
@@ -278,9 +448,12 @@ export class CdnFactory {
         return (app, scope) => {
             // The App is the only place the app name is known here; without it the
             // export falls back to the construct id and the Domain import misses.
+            // The App instance itself rides along for domainConfig resolution
+            // (certificate placement needs app.getUsEast1CertificateStack()).
             return new Cdn(scope, id, {
                 ...props,
-                appName: props.appName ?? app.getName()
+                appName: props.appName ?? app.getName(),
+                app: props.app ?? app
             });
         };
     }

package/dist/lib/patterns/aws/targets/fjallTargets.d.ts

@@ -23,15 +23,19 @@ export declare function fjallApp(appName: string, computeName?: string): FjallAl
 /**
  * Target helper for a Fjall CloudFront-fronted app.
  *
- * Requires the CDN stack to publish export `${safeApp}CdnDistributionDomainName`.
- * Phase 2 wires the emitter.
+ * Requires the CDN stack to publish export `${safeApp}CdnDistributionDomainName`
+ * — emitted by every `CloudFrontDistribution` given an `appName` (the
+ * `CdnFactory.build` path fills it from the App). Naming an app with no such
+ * export fails at CloudFormation execution, exactly as `fjallApp` documents.
  */
 export declare function fjallCdn(appName: string): FjallAliasTarget;
 /**
  * Target helper for a Fjall S3 static-site bucket.
  *
  * Requires the bucket stack to publish exports `${safeBucket}WebsiteEndpoint`
- * and `${safeBucket}WebsiteHostedZoneId`. Phase 2 wires these emitters.
+ * and `${safeBucket}WebsiteHostedZoneId` — emitted by website-enabled `S3`
+ * storage. Naming a bucket with no such exports fails at CloudFormation
+ * execution, exactly as `fjallApp` documents.
  */
 export declare function fjallBucket(bucketName: string): FjallAliasTarget;
 /**

package/dist/lib/patterns/aws/targets/fjallTargets.js

@@ -25,8 +25,10 @@ export function fjallApp(appName, computeName) {
 /**
  * Target helper for a Fjall CloudFront-fronted app.
  *
- * Requires the CDN stack to publish export `${safeApp}CdnDistributionDomainName`.
- * Phase 2 wires the emitter.
+ * Requires the CDN stack to publish export `${safeApp}CdnDistributionDomainName`
+ * — emitted by every `CloudFrontDistribution` given an `appName` (the
+ * `CdnFactory.build` path fills it from the App). Naming an app with no such
+ * export fails at CloudFormation execution, exactly as `fjallApp` documents.
  */
 export function fjallCdn(appName) {
     const resolved = resolveCdnTarget(appName);
@@ -42,7 +44,9 @@ export function fjallCdn(appName) {
  * Target helper for a Fjall S3 static-site bucket.
  *
  * Requires the bucket stack to publish exports `${safeBucket}WebsiteEndpoint`
- * and `${safeBucket}WebsiteHostedZoneId`. Phase 2 wires these emitters.
+ * and `${safeBucket}WebsiteHostedZoneId` — emitted by website-enabled `S3`
+ * storage. Naming a bucket with no such exports fails at CloudFormation
+ * execution, exactly as `fjallApp` documents.
  */
 export function fjallBucket(bucketName) {
     const resolved = resolveBucketTarget(bucketName);

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

@@ -367,22 +367,28 @@ export function addHostedZone(ctx, loadBalancer) {
             ...(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;
+        // apexRecord: "none" yields ONLY the domainName record itself (an
+        // ingress-migrated name now owned by a CDN's domainConfig) — routed-host,
+        // redirect-host records, listener, and certificates below are untouched
+        // (design 2026-08-17 cdn-domain-ownership C2).
+        if (domainConfig?.apexRecord !== "none") {
+            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;

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

@@ -260,6 +260,16 @@ export interface DomainBaseConfig {
      * Omit for a plain alias record.
      */
     routingPolicy?: EcsDomainRoutingPolicy;
+    /**
+     * The cluster's own DNS record for `domainName`. "alias" (default) mints
+     * the alias A record targeting the ALB — the long-standing behaviour.
+     * "none" keeps EVERYTHING else (certificates, HTTPS listener, redirect
+     * hosts and their records, host-routed service records) but yields the
+     * `domainName` record itself — the final state of an ingress migration
+     * where a CDN's `domainConfig` has taken the name over
+     * (design 2026-08-17 cdn-domain-ownership C2).
+     */
+    apexRecord?: "alias" | "none";
     /**
      * Hostnames (FQDNs within the zone, e.g. `"www.example.com"`) that
      * permanently redirect to `domainName` at the ALB. Each host gets an alias

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

@@ -11,8 +11,35 @@ export class AliasRecord extends Construct {
         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);
+        // 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.
+        const routingPolicy = props.region !== undefined
+            ? "latency"
+            : props.weight !== undefined
+                ? "weighted"
+                : props.geoLocation !== undefined
+                    ? "geolocation"
+                    : undefined;
+        // Route53 allows one geolocation record per location VALUE — serialise
+        // the location so the registry can compare siblings ("*" = the default
+        // wildcard record, which is equally one-per-(name, type)).
+        const geoLocationKey = props.geoLocation !== undefined
+            ? [
+                props.geoLocation.continentCode,
+                props.geoLocation.countryCode,
+                props.geoLocation.subdivisionCode
+            ]
+                .filter((part) => part !== undefined)
+                .join("/") || "*"
+            : undefined;
+        claimDnsRecord(this, props, "A", this.fqdn, {
+            setIdentifier: props.setIdentifier,
+            routingPolicy,
+            region: props.region,
+            ...(geoLocationKey !== undefined && { geoLocationKey })
+        });
         // 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", {

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

@@ -14,13 +14,27 @@ export interface DnsRecordCommonProps {
 export declare const DEFAULT_DNS_TTL_SECONDS = 300;
 export declare function resolveTtl(ttlSeconds: number | undefined): Duration;
 export declare function defaultDnsComment(recordType: string, fqdn: string): string;
+/**
+ * Routing-variant half of a claim — filled in by wrappers whose records can
+ * carry a routing policy (today: AliasRecord). Sibling variants with the
+ * same policy type and distinct setIdentifiers legally share a (zone, name,
+ * type) triple; the registry encodes Route53's coexistence rules.
+ */
+export interface DnsRecordClaimVariant {
+    readonly setIdentifier?: string;
+    readonly routingPolicy?: "latency" | "weighted" | "geolocation";
+    readonly region?: string;
+    /** Serialised geolocation value (continent/country/subdivision). */
+    readonly geoLocationKey?: string;
+}
 /**
  * Claim the (zone, name, type) triple in the app-scoped collision registry
  * (design D5, synth-side). Every wrapper in the dnsRecord family calls this
- * from its constructor so a second claimant — same stack or another stack in
- * the app — fails at synth instead of at CloudFormation deploy. Alias records
- * claim their underlying Route53 type ("A"). Observation only: no constructs
- * are created, so construct trees stay byte-identical.
+ * from its constructor so an illegal second claimant — same stack or another
+ * stack in the app — fails at synth instead of at CloudFormation deploy.
+ * Alias records claim their underlying Route53 type ("A") and pass their
+ * routing variant so legal policy siblings register cleanly. Observation
+ * only: no constructs are created, so construct trees stay byte-identical.
  */
-export declare function claimDnsRecord(construct: Construct, props: Pick<DnsRecordCommonProps, "zone" | "zoneName">, recordType: string, fqdn: string): void;
+export declare function claimDnsRecord(construct: Construct, props: Pick<DnsRecordCommonProps, "zone" | "zoneName">, recordType: string, fqdn: string, variant?: DnsRecordClaimVariant): void;
 export declare function applyDnsRecordTags(construct: Construct, props: Pick<DnsRecordCommonProps, "zoneName" | "costAllocationEnvironment" | "costAllocationDomain">): void;

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

@@ -15,17 +15,28 @@ export function defaultDnsComment(recordType, fqdn) {
 /**
  * Claim the (zone, name, type) triple in the app-scoped collision registry
  * (design D5, synth-side). Every wrapper in the dnsRecord family calls this
- * from its constructor so a second claimant — same stack or another stack in
- * the app — fails at synth instead of at CloudFormation deploy. Alias records
- * claim their underlying Route53 type ("A"). Observation only: no constructs
- * are created, so construct trees stay byte-identical.
+ * from its constructor so an illegal second claimant — same stack or another
+ * stack in the app — fails at synth instead of at CloudFormation deploy.
+ * Alias records claim their underlying Route53 type ("A") and pass their
+ * routing variant so legal policy siblings register cleanly. Observation
+ * only: no constructs are created, so construct trees stay byte-identical.
  */
-export function claimDnsRecord(construct, props, recordType, fqdn) {
+export function claimDnsRecord(construct, props, recordType, fqdn, variant) {
     registerDnsRecordClaim(construct, {
         zone: props.zone,
         zoneName: props.zoneName,
         fqdn,
-        recordType
+        recordType,
+        ...(variant?.setIdentifier !== undefined && {
+            setIdentifier: variant.setIdentifier
+        }),
+        ...(variant?.routingPolicy !== undefined && {
+            routingPolicy: variant.routingPolicy
+        }),
+        ...(variant?.region !== undefined && { region: variant.region }),
+        ...(variant?.geoLocationKey !== undefined && {
+            geoLocationKey: variant.geoLocationKey
+        })
     });
 }
 export function applyDnsRecordTags(construct, props) {

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

@@ -2,13 +2,23 @@ import type { IHostedZone } from "aws-cdk-lib/aws-route53";
 import type { IConstruct } from "constructs";
 /**
  * Synth-time DNS record-collision registry (design D5, synth-side half — the
- * deploy-time preflight against live zones is Phase 2).
+ * deploy-time preflight against live zones is the CLI/deploy-core domain
+ * gate).
  *
- * Route53 allows exactly one record set per (zone, name, type); a second
- * claimant today fails only at CloudFormation deploy with a raw "record set
- * already exists". This registry makes the collision loud at synth: every
- * construct in the dnsRecord wrapper family registers its claim here, and a
- * duplicate claim throws naming both claimant construct paths and the cure.
+ * Route53 allows exactly one record set per (zone, name, type) — EXCEPT for
+ * routing-policy variants, where sibling record sets share the (name, type)
+ * pair and are discriminated by `setIdentifier`. Sibling variants must all
+ * carry the same policy type, and latency variants must each use a distinct
+ * region. A shape Route53 rejects fails only at CloudFormation deploy with a
+ * raw "record set already exists" / "conflicting RRSet"; this registry makes
+ * it loud at synth: every construct in the dnsRecord wrapper family registers
+ * its claim here, and an illegal combination throws naming both claimant
+ * construct paths and the cure.
+ *
+ * Legal coexistence (design 2026-08-17 cdn-domain-ownership C3): two claims
+ * on one (zone, name, type) with the SAME routing-policy type and DISTINCT
+ * `setIdentifier`s — e.g. the compute cluster's latency apex alias and a
+ * CDN's latency apex alias during an ingress migration — register cleanly.
  *
  * Scoping: claims are held per App (the construct-tree root), so multiple CDK
  * Apps in one process — the vitest convention of a fresh `new CdkApp()` per
@@ -22,6 +32,7 @@ import type { IConstruct } from "constructs";
  * (resetForTesting + resetManifestCollector in beforeEach/afterEach) keeps
  * working without a third per-test call.
  */
+export type DnsRoutingPolicyType = "latency" | "weighted" | "geolocation";
 export interface DnsRecordClaim {
     /** Zone the record lands in — consulted for identity resolution. */
     readonly zone: IHostedZone;
@@ -34,14 +45,34 @@ export interface DnsRecordClaim {
      * — an alias and a plain A record on the same name are a real collision.
      */
     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.
+     */
+    readonly setIdentifier?: string;
+    /** Policy type of a variant claim — siblings must all match. */
+    readonly routingPolicy?: DnsRoutingPolicyType;
+    /**
+     * Latency region of a latency variant — Route53 allows one latency record
+     * per region per (name, type).
+     */
+    readonly region?: string;
+    /**
+     * Serialised location of a geolocation variant — Route53 allows one
+     * geolocation record per location value per (name, type).
+     */
+    readonly geoLocationKey?: string;
 }
 /**
  * Register a record-set claim for `scope`, throwing when a DIFFERENT
- * construct already claimed the same (zoneIdentity, recordName, recordType)
- * triple within the same App. Re-registration by the same construct path
- * (CDK aspects re-visiting, repeated synth) is idempotent. Pure observation:
- * no constructs are created or mutated, so construct trees — including the
- * eject-contract byte-identical composer IDs — are untouched.
+ * construct already claimed a shape Route53 cannot hold alongside it within
+ * the same App. Re-registration by the same construct path (CDK aspects
+ * re-visiting, repeated synth) is idempotent. Pure observation: no constructs
+ * are created or mutated, so construct trees — including the eject-contract
+ * byte-identical composer IDs — are untouched.
  */
 export declare function registerDnsRecordClaim(scope: IConstruct, claim: DnsRecordClaim): void;
 /**

package/dist/lib/utils/dnsRecordRegistry.js

@@ -1,5 +1,17 @@
 import { Token } from "aws-cdk-lib";
-/** Claims per App root: claim key → owning construct path. */
+/**
+ * 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.)
+ */
+function isVariantEntry(entry) {
+    return entry.routingPolicy !== undefined || entry.setIdentifier !== undefined;
+}
+/** Claims per App root: claim key → claimant entries (variants share a key). */
 let claimsByRoot = new WeakMap();
 /** Lowercase and strip the trailing dot — DNS names are case-insensitive. */
 function normaliseDnsName(name) {
@@ -18,13 +30,20 @@ function resolveZoneIdentity(zone, zoneName) {
     }
     return normaliseDnsName(zoneName);
 }
+function collisionError(claim, recordType, existing, claimantPath, detail) {
+    return new Error(`DNS record '${claim.fqdn}' (${recordType}) in zone '${claim.zoneName}': ` +
+        `already claimed by construct '${existing.path}' — duplicate claim by '${claimantPath}'. ` +
+        `${detail} ` +
+        `Keep one owner per record — satellites own their app records; the domain stack owns zone-level records. ` +
+        `Remove or rename one claimant, or run 'fjall domain records list ${claim.zoneName}' to inspect the zone.`);
+}
 /**
  * Register a record-set claim for `scope`, throwing when a DIFFERENT
- * construct already claimed the same (zoneIdentity, recordName, recordType)
- * triple within the same App. Re-registration by the same construct path
- * (CDK aspects re-visiting, repeated synth) is idempotent. Pure observation:
- * no constructs are created or mutated, so construct trees — including the
- * eject-contract byte-identical composer IDs — are untouched.
+ * construct already claimed a shape Route53 cannot hold alongside it within
+ * the same App. Re-registration by the same construct path (CDK aspects
+ * re-visiting, repeated synth) is idempotent. Pure observation: no constructs
+ * are created or mutated, so construct trees — including the eject-contract
+ * byte-identical composer IDs — are untouched.
  */
 export function registerDnsRecordClaim(scope, claim) {
     const root = scope.node.root;
@@ -40,19 +59,54 @@ export function registerDnsRecordClaim(scope, claim) {
         recordType
     ].join("|");
     const claimantPath = scope.node.path;
+    const entry = {
+        path: claimantPath,
+        setIdentifier: claim.setIdentifier,
+        routingPolicy: claim.routingPolicy,
+        region: claim.region,
+        geoLocationKey: claim.geoLocationKey
+    };
     const existing = claims.get(key);
     if (existing === undefined) {
-        claims.set(key, claimantPath);
+        claims.set(key, [entry]);
         return;
     }
-    if (existing === claimantPath) {
-        return;
+    for (const other of existing) {
+        if (other.path === claimantPath) {
+            return;
+        }
+        const bothVariants = isVariantEntry(other) && isVariantEntry(entry);
+        if (!bothVariants) {
+            // Simple vs simple, or simple vs variant — Route53 holds neither.
+            const detail = isVariantEntry(other) || isVariantEntry(entry)
+                ? "Route53 cannot mix a simple record set with routing-policy variants on one (zone, name, type) — give BOTH records the same routing-policy type with distinct setIdentifiers, or remove one."
+                : "Route53 allows one record set per (zone, name, type); CloudFormation would reject this at deploy.";
+            throw collisionError(claim, recordType, other, claimantPath, detail);
+        }
+        if (other.setIdentifier !== undefined &&
+            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) {
+            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" &&
+            other.region !== undefined &&
+            other.region === entry.region) {
+            throw collisionError(claim, recordType, other, claimantPath, `Both latency variants use region '${entry.region}' — Route53 allows one latency record per region; give the second variant a different region.`);
+        }
+        if (entry.routingPolicy === "geolocation" &&
+            other.geoLocationKey !== undefined &&
+            other.geoLocationKey === entry.geoLocationKey) {
+            throw collisionError(claim, recordType, other, claimantPath, `Both geolocation variants target location '${entry.geoLocationKey}' — Route53 allows one geolocation record per location value; give the second variant a different location.`);
+        }
     }
-    throw new Error(`DNS record '${claim.fqdn}' (${recordType}) in zone '${claim.zoneName}': ` +
-        `already claimed by construct '${existing}' — duplicate claim by '${claimantPath}'. ` +
-        `Route53 allows one record set per (zone, name, type); CloudFormation would reject this at deploy. ` +
-        `Keep one owner per record — satellites own their app records; the domain stack owns zone-level records. ` +
-        `Remove or rename one claimant, or run 'fjall domain records list ${claim.zoneName}' to inspect the zone.`);
+    existing.push(entry);
 }
 /**
  * Reset all claims (for testing). Called by `App.resetForTesting()` alongside

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "14.0.0",
+  "version": "14.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -80,8 +80,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1098.0",
-    "@fjall/generator": "^14.0.0",
-    "@fjall/util": "^14.0.0",
+    "@fjall/generator": "^14.1.0",
+    "@fjall/util": "^14.1.0",
     "constructs": "^10.7.2"
   },
   "overrides": {