@fjall/components-infrastructure 14.2.0 → 15.0.0

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

@@ -44,7 +44,7 @@ export function composeApexDomain(scope, props) {
         costAllocationDomain: props.zoneName
     });
     if (props.records && props.records.length > 0) {
-        composeTypedDnsRecords(scope, hostedZoneConstruct.hostedZone, props.zoneName, props.records);
+        composeTypedDnsRecords(scope, hostedZoneConstruct.hostedZone, props.zoneName, props.records, props.recordIds);
     }
     return {
         hostedZone: hostedZoneConstruct.hostedZone,

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

@@ -168,7 +168,16 @@ export type ICdnProps = S3CdnProps | AlbCdnProps | HttpCdnProps | SmartCdnProps;
  */
 export interface SmartCdnBehaviour {
     pathPattern: string;
-    origin: Storage | AnyCompute | string;
+    /**
+     * Origin for this path pattern. Omit to route the pattern to the
+     * distribution's DEFAULT origin — the common shape where behaviours exist
+     * to vary caching or allowed methods per path, not to change origins. An
+     * origin-less behaviour is the default behaviour varied per path, so its
+     * omitted `cachePolicy`/`allowedMethods` inherit the distribution's
+     * `cachePolicy`/`defaultAllowedMethods` (a behaviour with its own origin
+     * is an independent config and keeps the resource-layer fallbacks).
+     */
+    origin?: Storage | AnyCompute | string;
     cachePolicy?: CachePolicyPreset | ICachePolicy;
     allowedMethods?: "GET_HEAD" | "GET_HEAD_OPTIONS" | "ALL";
     /**
@@ -225,11 +234,27 @@ export declare class Cdn extends CloudFrontDistribution implements ICdn {
      */
     private createDomainRecord;
     /**
-     * Resolve ICdnProps to CloudFrontDistributionProps.
+     * Resolve ICdnProps to the distribution props PLUS the Cdn-owned origin
+     * record plans the resolution produced — one resolution pass, one result.
      */
     private static resolveProps;
     /**
-     * Transform smart behaviours to CdnBehaviour objects.
+     * Transform smart behaviours to CdnBehaviour objects. A behaviour with no
+     * origin routes to the distribution's default origin — the same resolved
+     * config, so the resource layer memoizes them onto one distribution
+     * origin entry.
+     *
+     * Knob inheritance is asymmetric BY CONTRACT. An origin-less behaviour IS
+     * the default behaviour varied per path (the shape
+     * `SmartCdnBehaviour.origin` advertises), so its omitted
+     * `cachePolicy`/`allowedMethods` inherit the DISTRIBUTION's defaults —
+     * otherwise a caching-only behaviour on an `allowedMethods: "ALL"` API
+     * distribution would snap its path back to the resource layer's GET/HEAD
+     * fallback and 403 every POST at the edge. A behaviour WITH its own
+     * origin keeps the legacy resource-layer fallbacks (GET_HEAD /
+     * CACHING_OPTIMIZED): those deployed behaviours are byte-frozen, and an
+     * independent origin is an independent config, not a variation of the
+     * default behaviour.
      */
     private static resolveBehaviours;
     /**

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

@@ -4,9 +4,10 @@ import { CloudFrontTarget, LoadBalancerTarget } from "aws-cdk-lib/aws-route53-ta
 import { CloudFrontDistribution } from "../../resources/aws/cdn/index.js";
 import { AliasRecord } from "../../resources/aws/networking/index.js";
 import { getSafeZoneName, toPascalCase } from "../../utils/capitaliseString.js";
+import { recordLabelWithin } from "../../utils/domainTypes.js";
 import { resolvePatternZone, resolvePatternCloudFrontCertificate } from "./patternDomain.js";
 import { isStorage } from "./storage.js";
-import { CdnEcsOriginResolver, recordLabelWithin, normaliseDnsName } from "./cdnAppOrigin.js";
+import { CdnEcsOriginResolver, cdnOriginRefusal, internalAlbMessage, normaliseDnsName } from "./cdnAppOrigin.js";
 import { isCompute, isEcsCompute, isLambdaCompute } from "./compute.js";
 /**
  * The distribution's own alias names, normalised — consumed by the
@@ -91,7 +92,7 @@ function validateCdnProps(props) {
     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 ` +
+            throw cdnOriginRefusal("C4", `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 " +
@@ -141,10 +142,8 @@ function validateCdnProps(props) {
         }
         const profile = computeRef?.getIngressProfile();
         if (profile?.internal) {
-            // E2 — same defect as the construct-origin lane: no public path in.
-            throw new Error("CDN alb origin: the load balancer is internal — CloudFront " +
-                "reaches origins over the public internet and cannot address an " +
-                "internal ALB. Make the load balancer internet-facing.");
+            // E2 — same defect as the construct-origin lane, same shared message.
+            throw cdnOriginRefusal("E2", internalAlbMessage("CDN alb origin: the load balancer", "Make the load balancer internet-facing."));
         }
         const effectiveProtocol = props.protocolPolicy ?? "HTTPS_ONLY";
         if (effectiveProtocol !== "HTTP_ONLY") {
@@ -159,16 +158,16 @@ function validateCdnProps(props) {
                     : 'Use originType "auto" with the compute as origin — the ' +
                         "cluster's only listener is HTTPS (443), so the sole working " +
                         "path is a certificate-covered origin hostname.";
-            throw new Error(`CDN alb origin with protocolPolicy '${effectiveProtocol}' can ` +
+            throw cdnOriginRefusal("E9", `CDN alb origin with protocolPolicy '${effectiveProtocol}' can ` +
                 "never complete a TLS handshake: CloudFront validates the origin " +
                 "certificate against the raw ELB hostname " +
                 "(*.elb.amazonaws.com), which no ACM certificate covers — every " +
                 `origin fetch fails with a 502. ${cure}`);
         }
         if (profile !== undefined && profile.listenerPort === 443) {
-            // E9 (HTTP_ONLY variant) — nothing listens on 80: a connect-timeout
+            // E9b (HTTP_ONLY variant) — nothing listens on 80: a connect-timeout
             // 504 instead of a TLS 502, equally broken.
-            throw new Error('CDN alb origin with protocolPolicy "HTTP_ONLY": the cluster\'s ' +
+            throw cdnOriginRefusal("E9b", 'CDN alb origin with protocolPolicy "HTTP_ONLY": the cluster\'s ' +
                 "only listener is HTTPS (443) — a certificate resolved, so " +
                 "nothing listens on port 80 and every origin fetch times out. " +
                 'Use originType "auto" with the compute as origin instead.');
@@ -221,14 +220,16 @@ export class Cdn extends CloudFrontDistribution {
         // ECS construct-reference origins resolve through one memoized resolver
         // (design 2026-08-18 cdn-app-origin, D3): the default origin and every
         // behaviour referencing the same compute share one resolution and at
-        // most one origin record.
-        const ecsOriginResolver = Cdn.createEcsOriginResolver(id, props);
-        const resolvedProps = Cdn.resolveProps(scope, id, props, domain, ecsOriginResolver);
-        super(scope, id, resolvedProps);
+        // most one origin record. The record plans ride the resolution RESULT —
+        // they exist only once every origin has resolved, so returning them from
+        // resolveProps makes the ordering a property of the data flow rather
+        // than a call-sequence convention on the resolver instance.
+        const resolved = Cdn.resolveProps(scope, id, props, domain);
+        super(scope, id, resolved.distributionProps);
         if (domain !== undefined && props.domainConfig !== undefined) {
             this.createDomainRecord(id, props.domainConfig, domain);
         }
-        this.createOriginRecords(ecsOriginResolver.getRecordPlans());
+        this.createOriginRecords(resolved.recordPlans);
     }
     static createEcsOriginResolver(id, props) {
         return new CdnEcsOriginResolver({
@@ -283,6 +284,13 @@ export class Cdn extends CloudFrontDistribution {
                 behaviour.originRecord === undefined) {
                 continue;
             }
+            if (behaviour.origin === undefined) {
+                throw new Error(`CDN '${id}': behaviour '${behaviour.pathPattern}' sets ` +
+                    "'originHostname'/'originRecord' but no 'origin' — an " +
+                    "origin-less behaviour routes to the distribution's default " +
+                    "origin, whose overrides live on the distribution props. Move " +
+                    "the override there, or give the behaviour its own origin.");
+            }
             if (typeof behaviour.origin === "string" ||
                 !isCompute(behaviour.origin) ||
                 !isEcsCompute(behaviour.origin)) {
@@ -315,16 +323,16 @@ export class Cdn extends CloudFrontDistribution {
         // two DIFFERENT computes resolved the same name — an inherently invalid
         // shape (one alias record cannot target two load balancers). Refuse it
         // with the cure instead of letting CDK's duplicate-construct-id throw.
-        const byHostname = new Map();
+        const seenHostnames = new Set();
         for (const plan of plans) {
             const key = normaliseDnsName(plan.hostname);
-            if (byHostname.has(key)) {
+            if (seenHostnames.has(key)) {
                 throw new Error(`CDN '${this.node.id}': two ECS compute origins resolved the ` +
                     `same origin hostname '${plan.hostname}' — one alias record ` +
                     "cannot target two load balancers. Give one of them a " +
                     "distinct originHostname.");
             }
-            byHostname.set(key, plan);
+            seenHostnames.add(key);
         }
         for (const plan of plans) {
             const safeHost = toPascalCase(getSafeZoneName(plan.hostname));
@@ -385,26 +393,35 @@ export class Cdn extends CloudFrontDistribution {
         });
     }
     /**
-     * Resolve ICdnProps to CloudFrontDistributionProps.
+     * Resolve ICdnProps to the distribution props PLUS the Cdn-owned origin
+     * record plans the resolution produced — one resolution pass, one result.
      */
-    static resolveProps(scope, id, props, domain, ecsOriginResolver) {
+    static resolveProps(scope, id, props, domain) {
+        const ecsOriginResolver = Cdn.createEcsOriginResolver(id, props);
         const defaultOrigin = Cdn.resolveDefaultOrigin(props, ecsOriginResolver);
-        const behaviours = Cdn.resolveBehaviours(props.behaviours, ecsOriginResolver);
+        const behaviours = Cdn.resolveBehaviours(props.behaviours, defaultOrigin, ecsOriginResolver, {
+            cachePolicy: props.cachePolicy,
+            allowedMethods: props.defaultAllowedMethods
+        });
         const appName = props.appName;
         const domainNames = props.domainNames ??
             (props.domainConfig !== undefined
                 ? [props.domainConfig.domainName]
                 : undefined);
-        // A default origin resolved through the ECS profile lane serves a
-        // hostname that differs from the viewer-facing aliases, so host
-        // fidelity via x-forwarded-host is the sensible default (design D3
-        // step 9). Explicit `forwardHostHeader: false` wins.
-        const impliedForwardHostHeader = props.originType === "auto" &&
+        // ANY origin resolved through the ECS profile lane serves a hostname
+        // that differs from the viewer-facing aliases, so host fidelity via
+        // x-forwarded-host is the sensible default (design D3 step 9) — for a
+        // behaviour's ECS origin exactly as for the default origin, since the
+        // one viewer-request function rides every behaviour. Explicit
+        // `forwardHostHeader: false` wins.
+        const hasEcsOrigin = (props.originType === "auto" &&
             isCompute(props.origin) &&
-            isEcsCompute(props.origin) &&
-            (domainNames?.length ?? 0) > 0
-            ? true
-            : undefined;
+            isEcsCompute(props.origin)) ||
+            (props.behaviours ?? []).some((behaviour) => behaviour.origin !== undefined &&
+                typeof behaviour.origin !== "string" &&
+                isCompute(behaviour.origin) &&
+                isEcsCompute(behaviour.origin));
+        const impliedForwardHostHeader = hasEcsOrigin && (domainNames?.length ?? 0) > 0 ? true : undefined;
         const certificate = props.certificate ??
             (props.certificateArn
                 ? Certificate.fromCertificateArn(scope, `${id}Certificate`, props.certificateArn)
@@ -419,35 +436,60 @@ export class Cdn extends CloudFrontDistribution {
             }
             : {};
         return {
-            appName,
-            defaultOrigin,
-            defaultCachePolicy: props.cachePolicy,
-            defaultAllowedMethods: props.defaultAllowedMethods,
-            behaviours,
-            domainNames,
-            certificate,
-            comment: props.comment,
-            enableLogging: props.enableLogging,
-            logBucket: props.logBucket,
-            priceClass: props.priceClass,
-            forwardHostHeader: props.forwardHostHeader ?? impliedForwardHostHeader,
-            accessGate: props.accessGate,
-            ...s3Routing
+            distributionProps: {
+                appName,
+                defaultOrigin,
+                defaultCachePolicy: props.cachePolicy,
+                defaultAllowedMethods: props.defaultAllowedMethods,
+                behaviours,
+                domainNames,
+                certificate,
+                comment: props.comment,
+                enableLogging: props.enableLogging,
+                logBucket: props.logBucket,
+                priceClass: props.priceClass,
+                forwardHostHeader: props.forwardHostHeader ?? impliedForwardHostHeader,
+                accessGate: props.accessGate,
+                ...s3Routing
+            },
+            recordPlans: ecsOriginResolver.getRecordPlans()
         };
     }
     /**
-     * Transform smart behaviours to CdnBehaviour objects.
+     * Transform smart behaviours to CdnBehaviour objects. A behaviour with no
+     * origin routes to the distribution's default origin — the same resolved
+     * config, so the resource layer memoizes them onto one distribution
+     * origin entry.
+     *
+     * Knob inheritance is asymmetric BY CONTRACT. An origin-less behaviour IS
+     * the default behaviour varied per path (the shape
+     * `SmartCdnBehaviour.origin` advertises), so its omitted
+     * `cachePolicy`/`allowedMethods` inherit the DISTRIBUTION's defaults —
+     * otherwise a caching-only behaviour on an `allowedMethods: "ALL"` API
+     * distribution would snap its path back to the resource layer's GET/HEAD
+     * fallback and 403 every POST at the edge. A behaviour WITH its own
+     * origin keeps the legacy resource-layer fallbacks (GET_HEAD /
+     * CACHING_OPTIMIZED): those deployed behaviours are byte-frozen, and an
+     * independent origin is an independent config, not a variation of the
+     * default behaviour.
      */
-    static resolveBehaviours(behaviours, ecsOriginResolver) {
+    static resolveBehaviours(behaviours, defaultOrigin, ecsOriginResolver, distributionDefaults) {
         if (!behaviours || behaviours.length === 0) {
             return undefined;
         }
-        return behaviours.map((behaviour) => ({
-            pathPattern: behaviour.pathPattern,
-            origin: Cdn.detectOriginFromResource(behaviour.origin, ecsOriginResolver),
-            cachePolicy: behaviour.cachePolicy,
-            allowedMethods: behaviour.allowedMethods
-        }));
+        return behaviours.map((behaviour) => behaviour.origin === undefined
+            ? {
+                pathPattern: behaviour.pathPattern,
+                origin: defaultOrigin,
+                cachePolicy: behaviour.cachePolicy ?? distributionDefaults.cachePolicy,
+                allowedMethods: behaviour.allowedMethods ?? distributionDefaults.allowedMethods
+            }
+            : {
+                pathPattern: behaviour.pathPattern,
+                origin: Cdn.detectOriginFromResource(behaviour.origin, ecsOriginResolver),
+                cachePolicy: behaviour.cachePolicy,
+                allowedMethods: behaviour.allowedMethods
+            });
     }
     /**
      * Resolve the default origin from ICdnProps.

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

@@ -18,12 +18,6 @@ import type { CdnOriginConfig } from "../../resources/aws/cdn/index.js";
 import type { IEcsCompute } from "./interfaces/compute.js";
 import { normaliseDnsName } from "../../resources/aws/compute/ingressProfile.js";
 export { normaliseDnsName };
-/**
- * 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.
- */
-export declare function recordLabelWithin(domain: string, zoneName: string): string;
 /** A Cdn-owned origin alias record to mint after the distribution exists. */
 export interface EcsOriginRecordPlan {
     hostname: string;
@@ -59,10 +53,25 @@ export interface CdnEcsOriginResolverOptions {
      * distribution props (default origin) and each behaviour entry. */
     overrides?: ReadonlyMap<IEcsCompute, EcsOriginOverride>;
 }
+/**
+ * The origin-lane refusal/warning catalogue (design 2026-08-18
+ * cdn-app-origin § E-catalogue; C4 is the origin-loop guard from design
+ * 2026-08-17 cdn-domain-ownership). Every catalogue verdict is thrown or
+ * logged through the helpers below so its code rides at the head of the
+ * message — a synth or deploy log line maps straight back to the catalogue
+ * entry, and its cure, without a source dive.
+ */
+export type CdnOriginIssueCode = "C4" | "E1" | "E2" | "E3" | "E4" | "E5" | "E6" | "E7" | "E8" | "E9" | "E9b" | "E10" | "E11" | "W1" | "W2";
+export declare function cdnOriginRefusal(code: CdnOriginIssueCode, message: string): Error;
+export declare function cdnOriginWarning(code: CdnOriginIssueCode, message: string): void;
+/**
+ * E2's invariant middle, shared by the construct-origin and alb lanes —
+ * the lanes differ only in subject and cure, never in the defect statement.
+ */
+export declare function internalAlbMessage(subject: string, cure: string): string;
 export declare class CdnEcsOriginResolver {
     private readonly options;
     private readonly resolutions;
-    private warnedUnknownCoverage;
     constructor(options: CdnEcsOriginResolverOptions);
     resolve(compute: IEcsCompute): ResolvedEcsOrigin;
     /** Every Cdn-owned record the resolutions so far require, one per compute. */

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

@@ -15,21 +15,8 @@
 import { Token } from "aws-cdk-lib";
 import { certificateCovers, forwardingVerdict, normaliseDnsName } from "../../resources/aws/compute/ingressProfile.js";
 export { normaliseDnsName };
-import { DNS_APEX } from "@fjall/util";
-import { isWithinZone } from "../../utils/domainTypes.js";
+import { isWithinZone, recordLabelWithin } from "../../utils/domainTypes.js";
 import { FjallLogger } from "../../utils/validationLogger.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.
- */
-export function recordLabelWithin(domain, zoneName) {
-    if (domain === zoneName) {
-        return DNS_APEX;
-    }
-    const suffix = `.${zoneName}`;
-    return domain.endsWith(suffix) ? domain.slice(0, -suffix.length) : domain;
-}
 const SHARED_CURE = "declare the hostname as a routing host on the receiving service " +
     "(services[].routing[].host) — one declaration adds the certificate SAN " +
     "(cluster-minted certificates), the listener rule, and the DNS record. " +
@@ -37,10 +24,23 @@ const SHARED_CURE = "declare the hostname as a routing host on the receiving ser
     "default action from forward to fixed-404, so a cluster serving its " +
     "domain through the default action must keep a forwarding path for it, " +
     'e.g. routing: [{ path: "/*" }, { host: "<origin hostname>" }].';
+export function cdnOriginRefusal(code, message) {
+    return new Error(`[${code}] ${message}`);
+}
+export function cdnOriginWarning(code, message) {
+    FjallLogger.warn(`[${code}] ${message}`);
+}
+/**
+ * E2's invariant middle, shared by the construct-origin and alb lanes —
+ * the lanes differ only in subject and cure, never in the defect statement.
+ */
+export function internalAlbMessage(subject, cure) {
+    return (`${subject} is internal — CloudFront reaches origins over the public ` +
+        `internet and cannot address an internal ALB. ${cure}`);
+}
 export class CdnEcsOriginResolver {
     options;
     resolutions = new Map();
-    warnedUnknownCoverage = false;
     constructor(options) {
         this.options = options;
     }
@@ -68,32 +68,31 @@ export class CdnEcsOriginResolver {
         const profile = compute.getIngressProfile();
         if (profile === undefined) {
             // E1 — pre-existing shape, kept: a cluster with no ALB cannot origin.
-            throw new Error(`CDN '${cdnId}': the ECS compute origin has no load balancer. ` +
+            throw cdnOriginRefusal("E1", `CDN '${cdnId}': the ECS compute origin has no load balancer. ` +
                 "Enable loadBalancer in the compute configuration, or front a " +
                 "different resource.");
         }
         if (profile.internal) {
             // E2 — CloudFront has no path into a VPC-internal ALB.
-            throw new Error(`CDN '${cdnId}': the ECS compute origin's load balancer is internal ` +
-                "— CloudFront reaches origins over the public internet and cannot " +
-                "address an internal ALB. Make the cluster's load balancer " +
-                'internet-facing (drop loadBalancer: "internal"), or front a ' +
-                "different resource.");
+            throw cdnOriginRefusal("E2", internalAlbMessage(`CDN '${cdnId}': the ECS compute origin's load balancer`, "Make the cluster's load balancer internet-facing (drop " +
+                'loadBalancer: "internal"), or front a different resource.'));
         }
         const { hostname, computeOwnsRecord } = this.selectHostname(compute, profile);
         // Origin-loop guard (C4, extended): the resolved hostname must not be
         // one of the distribution's own alias names.
         if (this.options.aliasNames.has(normaliseDnsName(hostname))) {
-            throw new Error(`CDN '${cdnId}': resolved origin hostname '${hostname}' is also one ` +
+            throw cdnOriginRefusal("C4", `CDN '${cdnId}': resolved origin hostname '${hostname}' is also one ` +
                 "of the distribution's own domain names — once DNS points that " +
                 "name at the distribution, every request loops CloudFront → " +
                 "CloudFront. Pick a dedicated origin hostname (originHostname), " +
                 "or serve the alias from the compute directly.");
         }
         if (profile.listenerPort === 80) {
-            // E4 — no certificate anywhere: the listener serves HTTP only, and a
-            // CloudFront origin fetch over HTTPS has nothing to shake hands with.
-            throw new Error(`CDN '${cdnId}': the ECS compute origin's listener serves HTTP only ` +
+            // E4 (port-80 arm) — the same designed condition as the no-domain arm
+            // in selectHostname: no domain anywhere ⇒ no certificate ⇒ the
+            // listener serves HTTP only, and a CloudFront origin fetch over HTTPS
+            // has nothing to shake hands with. One code, one cure.
+            throw cdnOriginRefusal("E4", `CDN '${cdnId}': the ECS compute origin's listener serves HTTP only ` +
                 "(the cluster has no domain, so no certificate resolved). A " +
                 "CloudFront origin needs a TLS-valid HTTPS origin. Give the " +
                 "cluster a domain (cluster.domainConfig), or use originType " +
@@ -112,7 +111,7 @@ export class CdnEcsOriginResolver {
                 profile.zoneName === undefined ||
                 !isWithinZone(hostname, profile.zoneName)) {
                 // E5 — a record we cannot mint: outside the cluster's zone.
-                throw new Error(`CDN '${cdnId}': originHostname '${hostname}' is outside the ECS ` +
+                throw cdnOriginRefusal("E5", `CDN '${cdnId}': originHostname '${hostname}' is outside the ECS ` +
                     `origin's hosted zone ('${profile.zoneName ?? "none"}'), so its ` +
                     "record cannot be minted here. Use a hostname inside the zone, " +
                     'or set originRecord: "none" and manage the record where the ' +
@@ -130,15 +129,17 @@ export class CdnEcsOriginResolver {
         if (coverage === "not-covered") {
             // E6 — provably uncovered: every attached certificate is enumerated
             // and none matches. TLS to the origin fails on every request.
-            throw new Error(`CDN '${cdnId}': no certificate on the ECS origin's listener covers ` +
+            throw cdnOriginRefusal("E6", `CDN '${cdnId}': no certificate on the ECS origin's listener covers ` +
                 `'${hostname}' (attached certificates cover: ` +
                 `${profile.certificateCoverage.kind === "unknown" ? "unknown" : profile.certificateCoverage.hostnames.join(", ") || "nothing"}). ` +
                 `Every origin fetch would fail TLS validation. Cure: ${SHARED_CURE}`);
         }
-        if (coverage === "unknown" && !this.warnedUnknownCoverage) {
-            this.warnedUnknownCoverage = true;
-            // W1 — opaque certificates: not decidable at synth, so warn once.
-            FjallLogger.warn(`CDN '${cdnId}': cannot verify that the ECS origin's listener ` +
+        if (coverage === "unknown") {
+            // W1 — opaque certificates: not decidable at synth. Once per compute
+            // by construction: resolveFresh is memoized per compute, so every
+            // opaque compute names its own hostname exactly once (the old
+            // resolver-wide latch swallowed every compute after the first).
+            cdnOriginWarning("W1", `CDN '${cdnId}': cannot verify that the ECS origin's listener ` +
                 `certificates cover '${hostname}' (imported certificate ARNs are ` +
                 "opaque at synth). If the cluster uses a managed domain, redeploy " +
                 "the domain stack with engine >= 14.2.0 so it publishes " +
@@ -150,13 +151,13 @@ export class CdnEcsOriginResolver {
         if (verdict.verdict === "none") {
             // E7 — the listener's default action is a fixed 404 and no rule
             // forwards the hostname: every origin fetch answers 404.
-            throw new Error(`CDN '${cdnId}': the ECS origin's listener would answer 404 for ` +
+            throw cdnOriginRefusal("E7", `CDN '${cdnId}': the ECS origin's listener would answer 404 for ` +
                 `'${hostname}' — its default action is a fixed 404 and no routing ` +
                 `rule forwards that hostname. Cure: ${SHARED_CURE}`);
         }
         if (verdict.verdict === "partial") {
             // W2 — some paths forward, others hit the fixed-404 default.
-            FjallLogger.warn(`CDN '${cdnId}': origin traffic for '${hostname}' forwards only for ` +
+            cdnOriginWarning("W2", `CDN '${cdnId}': origin traffic for '${hostname}' forwards only for ` +
                 `some paths (matching rules: ${verdict.patterns.join("; ")}); ` +
                 "requests outside those patterns answer the listener's fixed-404 " +
                 "default. Verify the patterns against the distribution's " +
@@ -195,7 +196,7 @@ export class CdnEcsOriginResolver {
                 // E10 — redirect hosts never serve traffic: the listener answers
                 // them with a 301 to the cluster domain, so an origin pointed there
                 // loops every viewer request through CloudFront → 301 → CloudFront.
-                throw new Error(`CDN '${cdnId}': originHostname '${explicit}' is a redirectHosts ` +
+                throw cdnOriginRefusal("E10", `CDN '${cdnId}': originHostname '${explicit}' is a redirectHosts ` +
                     "entry on the ECS origin — the listener 301s it to " +
                     `'${profile.domainName ?? "the cluster domain"}' and it never ` +
                     "serves traffic. Use a served hostname: a routing host, or the " +
@@ -204,7 +205,7 @@ export class CdnEcsOriginResolver {
             const computeOwnsRecord = profile.routedHosts.some((host) => normaliseDnsName(host) === explicitNormalised);
             if (computeOwnsRecord && originRecord !== undefined) {
                 // E8 — the compute already owns that hostname's record.
-                throw new Error(`CDN '${cdnId}': originRecord is set, but originHostname ` +
+                throw cdnOriginRefusal("E8", `CDN '${cdnId}': originRecord is set, but originHostname ` +
                     `'${explicit}' is a routing host — the compute already owns its ` +
                     "record (P1: the construct that declares a hostname owns its " +
                     "record). Drop originRecord.");
@@ -218,7 +219,7 @@ export class CdnEcsOriginResolver {
         if (candidates.length === 1 && candidates[0] !== undefined) {
             if (originRecord !== undefined) {
                 // E8 — same ownership rule as the explicit arm.
-                throw new Error(`CDN '${cdnId}': originRecord is set, but the origin resolved to ` +
+                throw cdnOriginRefusal("E8", `CDN '${cdnId}': originRecord is set, but the origin resolved to ` +
                     `routing host '${candidates[0]}' — the compute already owns its ` +
                     "record. Drop originRecord.");
             }
@@ -226,18 +227,18 @@ export class CdnEcsOriginResolver {
         }
         if (candidates.length > 1) {
             // E3 — ambiguous: several served hostnames could be the origin.
-            throw new Error(`CDN '${cdnId}': the ECS origin serves several hostnames ` +
+            throw cdnOriginRefusal("E3", `CDN '${cdnId}': the ECS origin serves several hostnames ` +
                 `(${candidates.join(", ")}) and the origin is ambiguous. Set ` +
                 "originHostname — on the distribution for its default origin, or " +
                 "on the behaviour entry — to the one the distribution should " +
                 "fetch from.");
         }
         if (profile.domainName === undefined) {
-            // E4 — nothing to derive from (and nothing a viewer could reach over
-            // TLS anyway; the no-domain listener is HTTP-only, so an explicit
-            // originHostname would only trade this error for the port-80 one —
-            // the catalogue cures are the honest ones).
-            throw new Error(`CDN '${cdnId}': the ECS compute origin has no domain to derive an ` +
+            // E4 (no-domain arm) — nothing to derive from (and nothing a viewer
+            // could reach over TLS anyway; the no-domain listener is HTTP-only,
+            // so an explicit originHostname would only trade this error for the
+            // port-80 arm — the catalogue cures are the honest ones).
+            throw cdnOriginRefusal("E4", `CDN '${cdnId}': the ECS compute origin has no domain to derive an ` +
                 "origin hostname from (and no certificate, so nothing serves " +
                 "HTTPS). Give the cluster a domain (cluster.domainConfig), or " +
                 'use originType "alb" with protocolPolicy "HTTP_ONLY" if ' +

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

@@ -76,7 +76,7 @@ export function composeDelegatedDomain(scope, props) {
     const nameServers = hostedZoneConstruct.nameServers ?? props.adoptedNameServers ?? [];
     const records = props.records ?? [];
     if (records.length > 0) {
-        composeTypedDnsRecords(scope, hostedZoneConstruct.hostedZone, effectiveZone, records);
+        composeTypedDnsRecords(scope, hostedZoneConstruct.hostedZone, effectiveZone, records, props.recordIds);
     }
     // Step 2 of the R2 two-step gate: issuing the cert before the delegation
     // NS has propagated hangs ACM DNS-validation, so "zone" stops here.

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

@@ -11,8 +11,17 @@ import type { DnsRecord } from "./interfaces/domain.js";
  * runtime guard catches user-crafted `{ kind, ... }` literals that lack
  * `bind()`.
  *
- * Construct-id formula (`${safeZone}${safeName}${type}Record${index}`) is
- * byte-identical to the legacy composer — this is an eject-contract
- * invariant (Phase 3 depends on stable IDs).
+ * Construct-id formulas (`recordIds` on `DomainCommonProps`):
+ * - `"indexed"` (default): `${safeZone}${safeName}${type}Record${index}` —
+ *   byte-identical to the legacy composer, an eject-contract invariant
+ *   (Phase 3 depends on stable IDs). Position-coupled, so the records list
+ *   is append-only for deployed zones.
+ * - `"stable"`: `${safeZone}${safeName}${type}Record` — position-free.
+ *   {@link assertStableIdsDerivable} refuses the two shapes that would
+ *   collide, with cures, before CDK's opaque duplicate-construct-id error
+ *   can fire.
+ * A per-record `id` (PascalCase alphanumeric) replaces the `safeName`
+ * segment in either mode — the escape hatch the stable-mode collision
+ * refusal names.
  */
-export declare function composeTypedDnsRecords(scope: Construct, zone: IHostedZone, zoneName: string, records: DnsRecord[]): void;
+export declare function composeTypedDnsRecords(scope: Construct, zone: IHostedZone, zoneName: string, records: DnsRecord[], recordIds?: "indexed" | "stable"): void;