@fjall/components-infrastructure 14.1.0 → 14.3.0

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

@@ -0,0 +1,215 @@
+/**
+ * Synth-time ingress profile for an ECS cluster's ALB (design 2026-08-18
+ * cdn-app-origin, D2). The profile is the one sanctioned answer to "what
+ * does this cluster's listener actually do?" for downstream constructs —
+ * today the `Cdn` construct-reference origin lane, which needs a TLS-valid
+ * origin hostname, certificate coverage, and a forwarding verdict without
+ * re-deriving any of it from props.
+ *
+ * P5 (model the machinery, don't paraphrase it): every fact here is exported
+ * from the SAME computation the emitting code uses — `default404` is the
+ * predicate `addLoadBalancerListener` passes to the listener factory, the
+ * rule structure derives from the `planListenerRules` plan that
+ * `registerServiceWithALB` itself emits from (including the single-service
+ * conditions-dropped branch), and the covered SAN set is the one
+ * `addHostedZone` mints. Never recompute these facts from cluster props
+ * elsewhere; extend the plan or the profile instead.
+ */
+import { FjallLogger } from "../../../utils/validationLogger.js";
+function normaliseRoutingRules(routing) {
+    return Array.isArray(routing) ? routing : routing ? [routing] : [];
+}
+function servicesWithPorts(services) {
+    return services.filter((s) => s.containers.some((c) => c.port !== undefined));
+}
+/**
+ * The listener's rule structure, planned once (P5). This is the SINGLE home
+ * of the branching: `registerServiceWithALB` emits from a service's plan
+ * entry, and the ingress-profile facts below (`computeListenerDefault404`,
+ * `enumerateListenerRules`) derive from the same plan — the emitter and the
+ * model cannot drift because neither re-derives the decisions.
+ */
+export function planListenerRules(services, redirectHosts) {
+    const withPorts = servicesWithPorts(services);
+    const isSingleService = withPorts.length === 1;
+    return {
+        services: withPorts.map((service) => {
+            const routingRules = normaliseRoutingRules(service.routing);
+            return {
+                service,
+                routingRules,
+                mode: isSingleService && routingRules.length <= 1
+                    ? "default"
+                    : "rules"
+            };
+        }),
+        redirectHosts
+    };
+}
+/**
+ * The listener's default-action predicate — the value
+ * `addLoadBalancerListener` passes to the listener factory as `default404`.
+ * `true` exactly when no service plan supplies an unconditioned default
+ * target group: ≥2 routes will exist (the emitter then attaches a fixed-404
+ * default and conditions every rule), or no service has a port (CDK rejects
+ * a listener with neither a default action nor targets).
+ */
+export function computeListenerDefault404(services) {
+    return !planListenerRules(services, []).services.some((plan) => plan.mode === "default");
+}
+/**
+ * The listener's rule structure as `registerServiceWithALB` and
+ * `addRedirectHostRules` will emit it — derived from the same
+ * `planListenerRules` plan the emitters consume: a `mode: "default"`
+ * service contributes NO conditioned rule (its target group is the listener
+ * default), and every redirect host contributes a host-matched 301 rule.
+ */
+export function enumerateListenerRules(services, redirectHosts) {
+    const plan = planListenerRules(services, redirectHosts);
+    const rules = [];
+    for (const servicePlan of plan.services) {
+        if (servicePlan.mode === "default")
+            continue;
+        for (const rule of servicePlan.routingRules) {
+            if (rule.host === undefined && rule.path === undefined)
+                continue;
+            rules.push({
+                ...(rule.host !== undefined && { host: rule.host }),
+                ...(rule.path !== undefined && { path: rule.path }),
+                kind: "forward"
+            });
+        }
+    }
+    for (const host of plan.redirectHosts) {
+        rules.push({ host, kind: "redirect" });
+    }
+    return rules;
+}
+/** Lowercase and strip the trailing dot — DNS names are case-insensitive. */
+export function normaliseDnsName(name) {
+    return name.toLowerCase().replace(/\.$/, "");
+}
+/**
+ * RFC 6125 certificate-name match: exact, or a single-label `*.` wildcard
+ * (matches exactly one additional label — `*.example.com` covers
+ * `a.example.com`, never `example.com` or `a.b.example.com`). DNS names
+ * compare ASCII case-insensitively (RFC 6125 §6.4.1 via RFC 4343).
+ */
+export function certNameMatches(pattern, hostname) {
+    const p = pattern.toLowerCase();
+    const h = hostname.toLowerCase();
+    if (p === h)
+        return true;
+    if (!p.startsWith("*."))
+        return false;
+    const suffix = p.slice(1); // ".example.com"
+    if (!h.endsWith(suffix))
+        return false;
+    const label = h.slice(0, h.length - suffix.length);
+    return label.length > 0 && !label.includes(".");
+}
+/**
+ * Does the listener's attached-certificate set cover `hostname`?
+ * Fail closed where decidable, honest where opaque (P3): only `enumerated`
+ * coverage may answer `not-covered`; a miss under `partial`/`unknown` is
+ * `unknown` because an opaque certificate may still cover the name.
+ */
+export function certificateCovers(coverage, hostname) {
+    if (coverage.kind === "unknown")
+        return "unknown";
+    if (coverage.hostnames.some((p) => certNameMatches(p, hostname))) {
+        return "covered";
+    }
+    return coverage.kind === "enumerated" ? "not-covered" : "unknown";
+}
+/**
+ * Would the listener forward `Host: <hostname>` requests, for all paths?
+ * Computed on the real rule model, never a flattened hostname list:
+ *
+ * - no fixed-404 default → the default action forwards every hostname;
+ * - a host-only rule for the hostname, a host-matched catch-all `/*` path
+ *   rule, or a host-less catch-all `/*` path rule, forwards all of its
+ *   paths;
+ * - rules that involve the hostname only together with a narrower path
+ *   condition (ANDed host+path, or host-less non-catch-all paths) forward
+ *   SOME paths — `partial`, with the patterns named so the caller can
+ *   surface them;
+ * - otherwise every request answers the fixed-404 default — `none`.
+ *
+ * Hostnames compare case-insensitively (DNS, RFC 4343) — the rule model
+ * carries the declared spelling, the caller's hostname may differ in case.
+ */
+export function forwardingVerdict(profile, hostname) {
+    if (!profile.default404)
+        return { verdict: "forwards" };
+    const wanted = normaliseDnsName(hostname);
+    const partial = [];
+    for (const rule of profile.rules) {
+        if (rule.kind !== "forward")
+            continue;
+        const hostMatches = rule.host !== undefined && normaliseDnsName(rule.host) === wanted;
+        if (hostMatches && (rule.path === undefined || rule.path === "/*")) {
+            return { verdict: "forwards" };
+        }
+        if (rule.host === undefined && rule.path === "/*") {
+            return { verdict: "forwards" };
+        }
+        if (hostMatches && rule.path !== undefined) {
+            partial.push(`Host=${rule.host} AND Path=${rule.path}`);
+        }
+        else if (rule.host === undefined && rule.path !== undefined) {
+            partial.push(`Path=${rule.path} (any host)`);
+        }
+    }
+    return partial.length > 0
+        ? { verdict: "partial", patterns: partial }
+        : { verdict: "none" };
+}
+export function buildIngressProfile(options) {
+    const { zoneFacts } = options;
+    const redirectHosts = zoneFacts?.redirectHosts ?? [];
+    return {
+        loadBalancer: options.loadBalancer,
+        internal: options.internal,
+        listenerPort: options.certificateAttached ? 443 : 80,
+        ...(zoneFacts !== undefined && {
+            hostedZone: zoneFacts.hostedZone,
+            zoneName: zoneFacts.zoneName,
+            domainName: zoneFacts.domainName
+        }),
+        routedHosts: zoneFacts?.routedHosts ?? [],
+        redirectHosts,
+        default404: computeListenerDefault404(options.services),
+        rules: enumerateListenerRules(options.services, redirectHosts),
+        certificateCoverage: zoneFacts?.certificateCoverage ?? {
+            // No domain → no certificates attached: the attached set is fully
+            // known (empty), which is the honest enumerated answer, not "unknown".
+            kind: "enumerated",
+            hostnames: []
+        }
+    };
+}
+/**
+ * W3 (design 2026-08-18 cdn-app-origin): a cluster whose listener default is
+ * fixed-404 while its `domainName` has a minted apex record and NO rule
+ * forwards it answers 404 on its own primary domain — usually the aftermath
+ * of adding a second routing rule (which flips the default action from
+ * forward to 404, `computeListenerDefault404`). A warning, not an error:
+ * pre-existing clusters can already be in this state, and narrowing them is
+ * not this check's mandate. Partial forwarding (path-split services) is the
+ * normal multi-route shape and does not warn.
+ */
+export function warnWhenRecordedApexUnforwarded(profile, apexRecordMinted, clusterName) {
+    if (!profile.default404)
+        return;
+    if (profile.domainName === undefined || !apexRecordMinted)
+        return;
+    if (forwardingVerdict(profile, profile.domainName).verdict !== "none")
+        return;
+    FjallLogger.warn(`Cluster '${clusterName}': the listener's default action is a fixed 404 ` +
+        `and no routing rule forwards '${profile.domainName}', but its alias ` +
+        "record is minted — requests to the cluster's own domain will answer " +
+        "404 Not Found. Multiple routing rules flip the listener default from " +
+        "forward to 404; keep a forwarding path for the domain, e.g. a " +
+        'routing rule { path: "/*" } on the service that should serve it.');
+}

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

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

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

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

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

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

package/dist/lib/utils/dnsRecordRegistry.js

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

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

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

package/dist/lib/utils/domainTypes.js

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

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

@@ -20,9 +20,18 @@
  * layer (generator-standards § Infrastructure Layer Boundaries).
  */
 import type { Node } from "constructs";
-import type { ManagedDomainBinding } from "@fjall/util";
+import { type ManagedDomainBinding, type ManagedDomainCoverage, type ManagedDomainExports } from "@fjall/util";
 export declare const MANAGED_DOMAIN_CONTEXT_PREFIX: "fjall:managedDomain:";
 export declare function getManagedDomainContextKey(zoneName: string): string;
+/**
+ * Companion channel to the binding (design 2026-08-18 cdn-app-origin, D5):
+ * the hostnames covered by exactly the certificates the same zone's binding
+ * names. A SEPARATE key on purpose — the binding parser above fails closed
+ * on unknown fields, so coverage could never ride the binding JSON without
+ * breaking older engines fed by a newer CLI.
+ */
+export declare const MANAGED_DOMAIN_COVERAGE_CONTEXT_PREFIX: "fjall:managedDomainCoverage:";
+export declare function getManagedDomainCoverageContextKey(zoneName: string): string;
 /**
  * Read the CLI-injected {@link ManagedDomainBinding} for `domainName`,
  * walking exact → parent zones (mirroring the CLI's
@@ -35,3 +44,51 @@ export declare function getManagedDomainContextKey(zoneName: string): string;
  * `context` prefixes every error, e.g. `Static site 'marketing'`.
  */
 export declare function readInjectedManagedDomainBinding(node: Node, domainName: string, context: string): ManagedDomainBinding | undefined;
+/**
+ * Read the CLI-injected {@link ManagedDomainCoverage} for the zone a binding
+ * already resolved to. Exact-key lookup on purpose (no parent-zone walk):
+ * the CLI injects coverage for precisely the zones it injects bindings for,
+ * and the caller passes the binding's own `zoneName`.
+ *
+ * Absent → undefined (a domain stack that predates the hosts outputs, or a
+ * bare-CDK synth) — consumers treat that as coverage-unknown and warn, never
+ * as not-covered. A present-but-corrupt value still throws (repo posture:
+ * corrupt context fails the synth rather than falling through), but UNKNOWN
+ * FIELDS ARE IGNORED, unlike the binding parser: coverage is advisory
+ * validation input, and forward tolerance here is what lets a future CLI add
+ * coverage fields without breaking older engines — the exact trap that
+ * forced this channel off the binding JSON in the first place.
+ */
+export declare function readInjectedManagedDomainCoverage(node: Node, zoneName: string, context: string): ManagedDomainCoverage | undefined;
+/**
+ * The one managed-domain identity a consumer acts on, resolved by the D2
+ * precedence every lane shares: an EXPLICIT `managedDomain` prop wins over
+ * the CLI-injected context binding (explicit beats injected); bare-CDK
+ * synth carries no context entry and yields undefined.
+ */
+export interface EffectiveManagedDomain {
+    managed: ManagedDomainBinding | ManagedDomainExports;
+    zoneName: string;
+    /**
+     * Zone id ready for `HostedZone.fromHostedZoneAttributes`: the binding's
+     * literal (crosses accounts and regions), or an `Fn.importValue` token on
+     * the exports form (same-account, same-region only).
+     */
+    hostedZoneId: string;
+    /**
+     * True when the identity is an EXPLICIT binding prop. An explicit binding
+     * may pin certificate ARNs older than the zone's current ones, so the
+     * injected coverage context — which describes the CURRENT certificates —
+     * must not be applied to it (the D5 provenance gate): folding it would
+     * over-claim coverage and invert P3. Injected bindings and the exports
+     * form (which resolves at deploy to the current certificate) are safe.
+     */
+    explicitPinnedBinding: boolean;
+}
+/**
+ * Resolve the effective managed-domain identity for `domainName` — the
+ * SINGLE home of the explicit-beats-injected precedence and of the
+ * binding-vs-exports zone-id branch, shared by the resources layer
+ * (`ecsNetworking.addHostedZone`) and the patterns layer (`patternDomain`).
+ */
+export declare function resolveEffectiveManagedDomain(node: Node, explicit: ManagedDomainBinding | ManagedDomainExports | undefined, domainName: string, context: string): EffectiveManagedDomain | undefined;

package/dist/lib/utils/managedDomainContext.js

@@ -19,10 +19,23 @@
  * (`patternDomain.resolvePatternZone`), and utils is their lowest common
  * layer (generator-standards § Infrastructure Layer Boundaries).
  */
+import { Fn } from "aws-cdk-lib";
+import { isManagedDomainBinding } from "@fjall/util";
 export const MANAGED_DOMAIN_CONTEXT_PREFIX = "fjall:managedDomain:";
 export function getManagedDomainContextKey(zoneName) {
     return `${MANAGED_DOMAIN_CONTEXT_PREFIX}${zoneName}`;
 }
+/**
+ * Companion channel to the binding (design 2026-08-18 cdn-app-origin, D5):
+ * the hostnames covered by exactly the certificates the same zone's binding
+ * names. A SEPARATE key on purpose — the binding parser above fails closed
+ * on unknown fields, so coverage could never ride the binding JSON without
+ * breaking older engines fed by a newer CLI.
+ */
+export const MANAGED_DOMAIN_COVERAGE_CONTEXT_PREFIX = "fjall:managedDomainCoverage:";
+export function getManagedDomainCoverageContextKey(zoneName) {
+    return `${MANAGED_DOMAIN_COVERAGE_CONTEXT_PREFIX}${zoneName}`;
+}
 const REQUIRED_STRING_FIELDS = ["zoneName", "hostedZoneId"];
 const OPTIONAL_STRING_FIELDS = [
     "certificateArn",
@@ -56,6 +69,89 @@ export function readInjectedManagedDomainBinding(node, domainName, context) {
     }
     return undefined;
 }
+/**
+ * Read the CLI-injected {@link ManagedDomainCoverage} for the zone a binding
+ * already resolved to. Exact-key lookup on purpose (no parent-zone walk):
+ * the CLI injects coverage for precisely the zones it injects bindings for,
+ * and the caller passes the binding's own `zoneName`.
+ *
+ * Absent → undefined (a domain stack that predates the hosts outputs, or a
+ * bare-CDK synth) — consumers treat that as coverage-unknown and warn, never
+ * as not-covered. A present-but-corrupt value still throws (repo posture:
+ * corrupt context fails the synth rather than falling through), but UNKNOWN
+ * FIELDS ARE IGNORED, unlike the binding parser: coverage is advisory
+ * validation input, and forward tolerance here is what lets a future CLI add
+ * coverage fields without breaking older engines — the exact trap that
+ * forced this channel off the binding JSON in the first place.
+ */
+export function readInjectedManagedDomainCoverage(node, zoneName, context) {
+    const key = getManagedDomainCoverageContextKey(zoneName);
+    const raw = node.tryGetContext(key);
+    if (raw === undefined)
+        return undefined;
+    let value = raw;
+    if (typeof raw === "string") {
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`${context}: CDK context '${key}' is not valid JSON (got '${raw}'). ` +
+                "The value must be a JSON ManagedDomainCoverage " +
+                "({ certificateHosts?, usEast1CertificateHosts? }) — re-run the " +
+                "deploy through the Fjall CLI, or correct the hand-set context " +
+                "entry.");
+        }
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${context}: CDK context '${key}' must be a JSON object ` +
+            `ManagedDomainCoverage (got ${JSON.stringify(value)}). Re-run the ` +
+            "deploy through the Fjall CLI, or correct the hand-set context entry.");
+    }
+    const record = value;
+    const coverage = {};
+    for (const field of [
+        "certificateHosts",
+        "usEast1CertificateHosts"
+    ]) {
+        const fieldValue = record[field];
+        if (fieldValue === undefined)
+            continue;
+        // An empty array is corruption, never data: a real certificate always
+        // covers at least its domain name, and the CLI never emits []. Letting
+        // it through would read as an enumerated "covers nothing" fact and turn
+        // an UNKNOWN coverage state into a definite (false) not-covered verdict.
+        if (!Array.isArray(fieldValue) ||
+            fieldValue.length === 0 ||
+            fieldValue.some((h) => typeof h !== "string" || h === "")) {
+            throw new Error(`${context}: CDK context '${key}' field '${field}' must be a ` +
+                `non-empty array of non-empty strings when present (got ` +
+                `${JSON.stringify(fieldValue)}). Re-run the deploy through the ` +
+                "Fjall CLI, or correct the hand-set context entry.");
+        }
+        coverage[field] = fieldValue;
+    }
+    return coverage;
+}
+/**
+ * Resolve the effective managed-domain identity for `domainName` — the
+ * SINGLE home of the explicit-beats-injected precedence and of the
+ * binding-vs-exports zone-id branch, shared by the resources layer
+ * (`ecsNetworking.addHostedZone`) and the patterns layer (`patternDomain`).
+ */
+export function resolveEffectiveManagedDomain(node, explicit, domainName, context) {
+    const managed = explicit ?? readInjectedManagedDomainBinding(node, domainName, context);
+    if (managed === undefined)
+        return undefined;
+    const isBinding = isManagedDomainBinding(managed);
+    return {
+        managed,
+        zoneName: managed.zoneName,
+        hostedZoneId: isBinding
+            ? managed.hostedZoneId
+            : Fn.importValue(managed.hostedZoneIdExport),
+        explicitPinnedBinding: explicit !== undefined && isBinding
+    };
+}
 function parseManagedDomainBinding(raw, zoneName, key, context) {
     let value = raw;
     if (typeof raw === "string") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "14.1.0",
+  "version": "14.3.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.1.0",
-    "@fjall/util": "^14.1.0",
+    "@fjall/generator": "^14.3.0",
+    "@fjall/util": "^14.3.0",
     "constructs": "^10.7.2"
   },
   "overrides": {