@fjall/components-infrastructure 14.1.0 → 14.3.0

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

@@ -0,0 +1,83 @@
+/**
+ * ECS construct-reference origin resolution for the `Cdn` pattern (design
+ * 2026-08-18 cdn-app-origin, D3). Given a fronted ECS compute, resolve a
+ * TLS-valid ORIGIN HOSTNAME from the compute's own ingress profile, decide
+ * who owns its DNS record (P1: the construct that declares a hostname owns
+ * its record — a `routing[].host` hostname is the compute's; a derived or
+ * free hostname is the Cdn's), and validate certificate coverage and
+ * listener forwarding at synth — fail closed where decidable, warn where
+ * opaque or partial (P3).
+ *
+ * The resolver is memoized per compute within one `Cdn`: the default origin
+ * and every behaviour referencing the same compute share one resolution and
+ * at most one record.
+ */
+import type { IHostedZone } from "aws-cdk-lib/aws-route53";
+import type { IApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+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 };
+/** A Cdn-owned origin alias record to mint after the distribution exists. */
+export interface EcsOriginRecordPlan {
+    hostname: string;
+    hostedZone: IHostedZone;
+    zoneName: string;
+    recordName: string;
+    loadBalancer: IApplicationLoadBalancer;
+}
+export interface ResolvedEcsOrigin {
+    hostname: string;
+    originConfig: CdnOriginConfig;
+    /** Present when the Cdn owns the record and `originRecord` is not "none". */
+    recordPlan?: EcsOriginRecordPlan;
+    /** True when the hostname is a compute-declared routing host (P1). */
+    computeOwnsRecord: boolean;
+}
+/**
+ * Explicit per-compute origin overrides: the distribution-level
+ * `originHostname`/`originRecord` for the default origin's compute, and each
+ * behaviour's own `originHostname`/`originRecord` for its compute — so every
+ * lane that can throw E3 can also cure it (design D3: behaviour origins get
+ * the same targeted validation AND the same override surface).
+ */
+export interface EcsOriginOverride {
+    originHostname?: string;
+    originRecord?: "alias" | "none";
+}
+export interface CdnEcsOriginResolverOptions {
+    cdnId: string;
+    /** The distribution's own alias names, normalised — the origin-loop guard. */
+    aliasNames: ReadonlySet<string>;
+    /** Per-compute explicit overrides — assembled by the Cdn from the
+     * 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;
+    constructor(options: CdnEcsOriginResolverOptions);
+    resolve(compute: IEcsCompute): ResolvedEcsOrigin;
+    /** Every Cdn-owned record the resolutions so far require, one per compute. */
+    getRecordPlans(): EcsOriginRecordPlan[];
+    private resolveFresh;
+    private explicitHostnameFor;
+    private effectiveOriginRecord;
+    private selectHostname;
+}

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

@@ -0,0 +1,252 @@
+/**
+ * ECS construct-reference origin resolution for the `Cdn` pattern (design
+ * 2026-08-18 cdn-app-origin, D3). Given a fronted ECS compute, resolve a
+ * TLS-valid ORIGIN HOSTNAME from the compute's own ingress profile, decide
+ * who owns its DNS record (P1: the construct that declares a hostname owns
+ * its record — a `routing[].host` hostname is the compute's; a derived or
+ * free hostname is the Cdn's), and validate certificate coverage and
+ * listener forwarding at synth — fail closed where decidable, warn where
+ * opaque or partial (P3).
+ *
+ * The resolver is memoized per compute within one `Cdn`: the default origin
+ * and every behaviour referencing the same compute share one resolution and
+ * at most one record.
+ */
+import { Token } from "aws-cdk-lib";
+import { certificateCovers, forwardingVerdict, normaliseDnsName } from "../../resources/aws/compute/ingressProfile.js";
+export { normaliseDnsName };
+import { isWithinZone, recordLabelWithin } from "../../utils/domainTypes.js";
+import { FjallLogger } from "../../utils/validationLogger.js";
+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. " +
+    "CAUTION: adding a SECOND routing rule to a service flips the listener " +
+    "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();
+    constructor(options) {
+        this.options = options;
+    }
+    resolve(compute) {
+        const memoized = this.resolutions.get(compute);
+        if (memoized !== undefined) {
+            return memoized;
+        }
+        const resolution = this.resolveFresh(compute);
+        this.resolutions.set(compute, resolution);
+        return resolution;
+    }
+    /** Every Cdn-owned record the resolutions so far require, one per compute. */
+    getRecordPlans() {
+        const plans = [];
+        for (const resolution of this.resolutions.values()) {
+            if (resolution.recordPlan !== undefined) {
+                plans.push(resolution.recordPlan);
+            }
+        }
+        return plans;
+    }
+    resolveFresh(compute) {
+        const { cdnId } = this.options;
+        const profile = compute.getIngressProfile();
+        if (profile === undefined) {
+            // E1 — pre-existing shape, kept: a cluster with no ALB cannot origin.
+            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 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 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 (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 " +
+                '"alb" with protocolPolicy "HTTP_ONLY" if plaintext origin ' +
+                "traffic is acceptable.");
+        }
+        // Record-ownership feasibility BEFORE coverage/forwarding (design D3
+        // step 3): an out-of-zone hostname's only real cures are an in-zone
+        // name or originRecord: "none" — deciding coverage first would hand the
+        // user E6's routing-host cure, which ECS itself refuses out-of-zone.
+        let recordPlan;
+        if (!computeOwnsRecord && this.effectiveOriginRecord(compute) !== "none") {
+            // The Cdn owns the record (P1). Zone facts are guaranteed here: a
+            // 443 listener implies a domain, which implies zone identity.
+            if (profile.hostedZone === undefined ||
+                profile.zoneName === undefined ||
+                !isWithinZone(hostname, profile.zoneName)) {
+                // E5 — a record we cannot mint: outside the cluster's zone.
+                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 ' +
+                    "zone lives.");
+            }
+            recordPlan = {
+                hostname,
+                hostedZone: profile.hostedZone,
+                zoneName: profile.zoneName,
+                recordName: recordLabelWithin(hostname, profile.zoneName),
+                loadBalancer: profile.loadBalancer
+            };
+        }
+        const coverage = certificateCovers(profile.certificateCoverage, hostname);
+        if (coverage === "not-covered") {
+            // E6 — provably uncovered: every attached certificate is enumerated
+            // and none matches. TLS to the origin fails on every request.
+            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") {
+            // 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 " +
+                "certificate-coverage outputs and this becomes checkable; for " +
+                "imported certificates, verify the SANs cover the hostname — TLS " +
+                "fails at runtime if not.");
+        }
+        const verdict = forwardingVerdict(profile, hostname);
+        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 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.
+            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 " +
+                "behaviours.");
+        }
+        return {
+            hostname,
+            // The hostname is certificate-covered, so the resource layer's
+            // HTTPS_ONLY default is exactly right — no protocol override.
+            originConfig: { type: "http", domainName: hostname },
+            ...(recordPlan !== undefined && { recordPlan }),
+            computeOwnsRecord
+        };
+    }
+    explicitHostnameFor(compute) {
+        return this.options.overrides?.get(compute)?.originHostname;
+    }
+    effectiveOriginRecord(compute) {
+        return this.options.overrides?.get(compute)?.originRecord;
+    }
+    selectHostname(compute, profile) {
+        const { cdnId } = this.options;
+        const explicit = this.explicitHostnameFor(compute);
+        const originRecord = this.effectiveOriginRecord(compute);
+        if (explicit !== undefined) {
+            if (Token.isUnresolved(explicit)) {
+                throw new Error(`CDN '${cdnId}': originHostname must be a literal hostname (got ` +
+                    "an unresolved token). Coverage, forwarding, and the origin " +
+                    "record are synth-time decisions — pass the concrete name.");
+            }
+            // DNS names are case-insensitive (RFC 4343): every membership test
+            // compares normalised, so a case-differing spelling cannot slip past
+            // the redirect/ownership guards the way it cannot slip past ACM.
+            const explicitNormalised = normaliseDnsName(explicit);
+            if (profile.redirectHosts.some((host) => normaliseDnsName(host) === explicitNormalised)) {
+                // 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 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 " +
+                    "derived origin name (omit originHostname).");
+            }
+            const computeOwnsRecord = profile.routedHosts.some((host) => normaliseDnsName(host) === explicitNormalised);
+            if (computeOwnsRecord && originRecord !== undefined) {
+                // E8 — the compute already owns that hostname's record.
+                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.");
+            }
+            return { hostname: explicit, computeOwnsRecord };
+        }
+        // Auto-resolution: routed hosts that are not the distribution's own
+        // aliases. (Redirect hosts can never appear — ECS enforces
+        // serve-XOR-redirect at synth.)
+        const candidates = profile.routedHosts.filter((host) => !this.options.aliasNames.has(normaliseDnsName(host)));
+        if (candidates.length === 1 && candidates[0] !== undefined) {
+            if (originRecord !== undefined) {
+                // E8 — same ownership rule as the explicit arm.
+                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.");
+            }
+            return { hostname: candidates[0], computeOwnsRecord: true };
+        }
+        if (candidates.length > 1) {
+            // E3 — ambiguous: several served hostnames could be the origin.
+            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 (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 ' +
+                "plaintext origin traffic is acceptable.");
+        }
+        return {
+            hostname: `origin.${profile.domainName}`,
+            computeOwnsRecord: false
+        };
+    }
+}

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

@@ -5,7 +5,7 @@ import { type IApplicationLoadBalancer, type ApplicationListener } from "aws-cdk
 import { Construct } from "constructs";
 import { type IEcsCompute } from "./interfaces/compute.js";
 import { type SecretImport } from "../../resources/aws/secrets/index.js";
-import EcsCluster, { type EcsClusterProps } from "../../resources/aws/compute/ecs.js";
+import EcsCluster, { type EcsClusterProps, type EcsIngressProfile } from "../../resources/aws/compute/ecs.js";
 export { ScalingType } from "./computeEcsTypes.js";
 export type { EcsCapacityProvider, Ec2CapacityConfig, RemoteConnectionSpec, EcsCapacityProviderConfig, EcsContainerConfig, ContainerDependency, ContainerVolume, EcsScheduledTaskConfig, EcsLifecycleHookMigrationsConfig, EcsPostDeployMigrationsConfig, EcsHookMigrationsConfig, EcsMigrationsConfig, EcsMigrationsMode, EcsCircuitBreakerConfig, EcsScalingConfig, EcsClusterConfig, EcsRoutingConfig, EcsServiceConfig, ServiceLogAlarm, EcsComputeProps } from "./computeEcsTypes.js";
 import { ScalingType, type EcsCapacityProviderConfig, type EcsCapacityProvider, type EcsContainerConfig, type EcsScalingConfig, type EcsServiceConfig, type EcsComputeProps, type QueueScalingConfig } from "./computeEcsTypes.js";
@@ -227,6 +227,14 @@ export declare class EcsCompute extends Construct implements IEcsCompute {
     getCluster(): ICluster;
     /** Get the Application Load Balancer if one was created. */
     getLoadBalancer(): IApplicationLoadBalancer | undefined;
+    /**
+     * Synth-time ingress profile (design 2026-08-18 cdn-app-origin, D2):
+     * listener facts, zone identity, and certificate coverage for constructs
+     * that front this compute — the `Cdn` construct-reference origin lane
+     * resolves its origin hostname against it. Undefined when the compute has
+     * no load balancer.
+     */
+    getIngressProfile(): EcsIngressProfile | undefined;
     /** Get a specific service by name. */
     getService(name: string): IBaseService | undefined;
     /** Get all services in the cluster. */

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

@@ -1653,6 +1653,16 @@ export class EcsCompute extends Construct {
     getLoadBalancer() {
         return this.ecsCluster.getLoadBalancer();
     }
+    /**
+     * Synth-time ingress profile (design 2026-08-18 cdn-app-origin, D2):
+     * listener facts, zone identity, and certificate coverage for constructs
+     * that front this compute — the `Cdn` construct-reference origin lane
+     * resolves its origin hostname against it. Undefined when the compute has
+     * no load balancer.
+     */
+    getIngressProfile() {
+        return this.ecsCluster.getIngressProfile();
+    }
     /** Get a specific service by name. */
     getService(name) {
         return this.ecsCluster.getService(name);

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;

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

@@ -16,15 +16,29 @@ import { DNS_APEX } from "@fjall/util";
  * 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 function composeTypedDnsRecords(scope, zone, zoneName, records) {
+export function composeTypedDnsRecords(scope, zone, zoneName, records, recordIds = "indexed") {
     const safeZone = toPascalCase(getSafeZoneName(zoneName));
+    if (recordIds === "stable") {
+        assertStableIdsDerivable(zoneName, records);
+    }
     records.forEach((record, index) => {
-        const safeName = toPascalCase(record.name === DNS_APEX ? "Apex" : record.name);
-        const constructId = `${safeZone}${safeName}${record.type}Record${index}`;
+        const safeName = recordIdNameSegment(record);
+        const constructId = recordIds === "stable"
+            ? `${safeZone}${safeName}${record.type}Record`
+            : `${safeZone}${safeName}${record.type}Record${index}`;
         const common = {
             zone,
             zoneName,
@@ -40,6 +54,9 @@ export function composeTypedDnsRecords(scope, zone, zoneName, records) {
             }
             new AliasRecord(scope, constructId, {
                 ...common,
+                // A declared AAAA alias must DEPLOY as AAAA — the resource defaults
+                // to "A" for its pattern-internal (IPv4) call sites only.
+                recordType: record.type,
                 target: target
             });
             return;
@@ -102,6 +119,71 @@ export function composeTypedDnsRecords(scope, zone, zoneName, records) {
         }
     });
 }
+/**
+ * Construct-id name segment: an explicit `id` verbatim (validated — it
+ * becomes a CloudFormation logical-ID segment), else the pascal-cased
+ * record name. The no-`id` derivation is byte-identical to the legacy
+ * inline formula (eject contract).
+ */
+function recordIdNameSegment(record) {
+    if (record.id !== undefined) {
+        if (!/^[A-Za-z][A-Za-z0-9]*$/.test(record.id)) {
+            throw new Error(`DNS record '${record.name}' (${record.type}): 'id' must be ` +
+                `alphanumeric starting with a letter (got '${record.id}') — it ` +
+                "becomes a CloudFormation logical-ID segment.");
+        }
+        return record.id;
+    }
+    return toPascalCase(record.name === DNS_APEX ? "Apex" : record.name);
+}
+/**
+ * Stable-mode pre-flight: refuse the two list shapes whose derived
+ * construct ids would collide, each with its own cure, BEFORE CDK's opaque
+ * "already a Construct with name" error can fire.
+ *
+ * - Duplicate (name, type) pairs are illegal Route53 regardless of id
+ *   scheme (one record set per (zone, name, type) — the same doctrine the
+ *   DNS claim registry enforces across constructs; this vocabulary cannot
+ *   express routing-policy variants). Indexed mode surfaces them via the
+ *   registry at claim time; stable mode must refuse before construction.
+ * - DISTINCT records whose derived construct ids concatenate to one string
+ *   — same-type names that sanitise to one PascalCase segment (e.g.
+ *   'mail-eu' and 'mailEu'), or cross-type segment/type ambiguity (id
+ *   'ApiAAA' + type 'A' vs segment 'Api' + type 'AAAA' both derive
+ *   'ApiAAAARecord') — are legal Route53 but collide as construct ids; the
+ *   per-record `id` escape hatch disambiguates. Keyed on the FULL derived
+ *   id, never on (segment, type) pairs, precisely so the concatenation
+ *   ambiguity cannot slip past to CDK.
+ */
+function assertStableIdsDerivable(zoneName, records) {
+    const byRecordSet = new Map();
+    const byConstructId = new Map();
+    for (const record of records) {
+        const setKey = [
+            record.name.toLowerCase().replace(/\.$/, ""),
+            record.type
+        ].join("|");
+        const priorSet = byRecordSet.get(setKey);
+        if (priorSet !== undefined) {
+            throw new Error(`DNS record '${record.name}' (${record.type}) in zone '${zoneName}': ` +
+                "declared twice in this records list. Route53 allows one record " +
+                "set per (zone, name, type); CloudFormation would reject this at " +
+                "deploy. Merge the values into one entry (multi-value records " +
+                "take a string array), or remove one.");
+        }
+        byRecordSet.set(setKey, record);
+        const constructKey = `${recordIdNameSegment(record)}${record.type}Record`;
+        const prior = byConstructId.get(constructKey);
+        if (prior !== undefined) {
+            throw new Error(`DNS records '${prior.name}' (${prior.type}) and '${record.name}' ` +
+                `(${record.type}) in zone '${zoneName}': both derive record ` +
+                `construct id '${constructKey}' under recordIds: "stable". Give ` +
+                "one of them a distinct per-record 'id' (PascalCase " +
+                "alphanumeric) to disambiguate.");
+        }
+        byConstructId.set(constructKey, record);
+    }
+}
 // Parse "10 mail.example.com" → { priority: 10, hostName: "mail.example.com" }.
 function parseMxValue(raw) {
     const parts = raw.trim().split(/\s+/);

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

@@ -1,6 +1,6 @@
 import { CfnOutput, Stack, Stage, Token } from "aws-cdk-lib";
 import { HostedZone as AWSHostedZone } from "aws-cdk-lib/aws-route53";
-import { getDomainExportNames, getDomainUsEast1CertificatesStackName } from "@fjall/util";
+import { getDomainExportNames, getDomainUsEast1CertificatesStackName, hostsExportPartName, serialiseHostsChunks } from "@fjall/util";
 import { DomainCertificate } from "../../resources/aws/networking/domainCertificate.js";
 import { toPascalCase } from "../../utils/capitaliseString.js";
 const US_EAST_1 = "us-east-1";
@@ -42,6 +42,13 @@ export function composeDomainCertificates(scope, composition) {
                 costAllocationEnvironment: composition.costAllocationEnvironment,
                 costAllocationDomain: composition.costAllocationDomain
             });
+            // D5 (design 2026-08-18 cdn-app-origin): publish the hostnames this
+            // certificate covers beside its ARN export — SAME per-certificate
+            // identity, so a consumer can bind coverage for exactly the
+            // certificates whose ARNs it binds, never a zone-level aggregate
+            // (which would list hostnames of certificates that are not on the
+            // consumer's listener and over-claim coverage).
+            emitHostsOutputs(scope, `${certId}Hosts`, getDomainExportNames(normalised.domainName).certificateHosts, certificateHosts(normalised));
             certificates.set(normalised.domainName, dc.certificate);
             return;
         }
@@ -80,6 +87,7 @@ function mintCloudFrontCertificate(scope, composition, cert, certId) {
             exportCertificateArn: false
         });
         emitUsEast1Export(scope, composition, dc);
+        emitUsEast1HostsOutput(scope, composition, cert);
         return dc.certificate;
     }
     const pairedStack = resolvePairedUsEast1Stack(domainStack, composition, cert);
@@ -104,8 +112,65 @@ function mintCloudFrontCertificate(scope, composition, cert, certId) {
         exportCertificateArn: false
     });
     emitUsEast1Export(pairedStack, composition, dc);
+    // The hosts output lands on the MAIN domain stack even though the
+    // certificate lives in the paired stack: the SAN list is a synth-time
+    // literal (no cross-region reference), and the CLI's existing main-stack
+    // DescribeStacks read must reach it without touching the paired-stack
+    // reader (design 2026-08-18 cdn-app-origin, D5).
+    emitUsEast1HostsOutput(domainStack, composition, cert);
     return dc.certificate;
 }
+/** Hostnames a certificate covers: its domainName plus every SAN, deduped. */
+function certificateHosts(cert) {
+    return [
+        ...new Set([cert.domainName, ...(cert.subjectAlternativeNames ?? [])])
+    ];
+}
+/**
+ * CloudFormation caps output values at 1024 bytes: a certificate with
+ * enough — or long enough — SANs would fail the WHOLE domain-stack deploy
+ * with an opaque CFN error if its hosts list rode one output. Hosts lists
+ * that fit keep the base export name and construct ID byte-identical to
+ * the single-output era (no logical-ID churn on deployed stacks);
+ * oversized lists are emitted as a part family (`<base>-1`, `<base>-2`, …,
+ * each a self-contained JSON array under the threshold) with the base name
+ * OMITTED — a consumer that only knows the base name reads absence as
+ * coverage-unknown, never a partial list it would misread as complete (see
+ * `hostsExportPartName`). Coverage is therefore always published; the old
+ * over-limit fail-open (skip the output, coverage permanently
+ * unverifiable) is gone. The chunking algorithm (`serialiseHostsChunks`)
+ * is homed in @fjall/util so the CLI's eject templates split identically.
+ */
+function emitHostsOutputs(scope, keyPrefix, baseExportName, hosts) {
+    const chunks = serialiseHostsChunks(hosts);
+    const single = chunks.length === 1 ? chunks[0] : undefined;
+    if (single !== undefined) {
+        new CfnOutput(scope, keyPrefix, {
+            key: keyPrefix,
+            value: single,
+            exportName: baseExportName
+        });
+        return;
+    }
+    chunks.forEach((chunk, index) => {
+        const id = `${keyPrefix}${index + 1}`;
+        new CfnOutput(scope, id, {
+            key: id,
+            value: chunk,
+            exportName: hostsExportPartName(baseExportName, index + 1)
+        });
+    });
+}
+/**
+ * The zone-level `<zone>-us-east-1-certificate-hosts` output (D5 companion
+ * to `emitUsEast1Export`): the hostnames the viewer certificate covers,
+ * always minted on the MAIN domain stack so the D2 DescribeStacks read
+ * reaches it in one call regardless of where the certificate itself lives.
+ */
+function emitUsEast1HostsOutput(scope, composition, cert) {
+    const exports = getDomainExportNames(composition.effectiveZoneName);
+    emitHostsOutputs(scope, `${composition.safeZone}UsEast1CertificateHosts`, exports.usEast1CertificateHosts, certificateHosts(cert));
+}
 /**
  * The zone-level `<zone>-us-east-1-certificate-arn` export
  * (`getDomainExportNames(...).usEast1CertificateArn` — the SSOT

package/dist/lib/patterns/aws/interfaces/compute.d.ts

@@ -19,6 +19,7 @@ import { type IAutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
 import { type ISecurityGroup, type IConnectable } from "aws-cdk-lib/aws-ec2";
 import { type IGrantable, type Grant } from "aws-cdk-lib/aws-iam";
 import { type Construct } from "constructs";
+import type { EcsIngressProfile } from "../../../resources/aws/compute/ingressProfile.js";
 /**
  * Compute type discriminator.
  * Used to determine which specific interface applies.
@@ -66,6 +67,12 @@ export interface IEcsCompute extends ICompute, IConnectable {
      * for HTTPS, 80 for HTTP); does not indicate protocol.
      */
     getPrimaryListenerPort(): number | undefined;
+    /**
+     * Synth-time ingress profile (design 2026-08-18 cdn-app-origin, D2):
+     * listener facts, zone identity, and certificate coverage for constructs
+     * that front this compute. Undefined when there is no load balancer.
+     */
+    getIngressProfile(): EcsIngressProfile | undefined;
 }
 /**
  * Lambda compute interface.