@fjall/components-infrastructure 2.34.0 → 3.1.0

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

@@ -1,15 +1,16 @@
 import { Construct } from "constructs";
 import { CnameRecord as CdkCnameRecord } from "aws-cdk-lib/aws-route53";
-import { applyDnsRecordTags, defaultDnsComment, resolveFqdn, resolveTtl } from "./dnsRecordBase.js";
+import { applyDnsRecordTags, claimDnsRecord, defaultDnsComment, resolveRecordFqdn, resolveTtl } from "./dnsRecordBase.js";
 export class CnameRecord extends Construct {
     record;
     description;
     fqdn;
     constructor(scope, id, props) {
         super(scope, id);
-        this.fqdn = resolveFqdn(props.zoneName, props.recordName);
+        this.fqdn = resolveRecordFqdn(props.recordName, props.zoneName);
         this.description =
             props.description ?? defaultDnsComment("CNAME", this.fqdn);
+        claimDnsRecord(this, props, "CNAME", this.fqdn);
         this.record = new CdkCnameRecord(this, "Record", {
             zone: props.zone,
             recordName: this.fqdn,

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

@@ -1,6 +1,7 @@
 import { Duration } from "aws-cdk-lib";
 import { type Construct } from "constructs";
 import type { IHostedZone } from "aws-cdk-lib/aws-route53";
+export { resolveRecordFqdn } from "../../../../utils/domainTypes.js";
 export interface DnsRecordCommonProps {
     readonly zone: IHostedZone;
     readonly zoneName: string;
@@ -11,7 +12,15 @@ export interface DnsRecordCommonProps {
     readonly costAllocationDomain?: string;
 }
 export declare const DEFAULT_DNS_TTL_SECONDS = 300;
-export declare function resolveFqdn(zoneName: string, recordName: string): string;
 export declare function resolveTtl(ttlSeconds: number | undefined): Duration;
 export declare function defaultDnsComment(recordType: string, fqdn: string): string;
+/**
+ * Claim the (zone, name, type) triple in the app-scoped collision registry
+ * (design D5, synth-side). Every wrapper in the dnsRecord family calls this
+ * from its constructor so a second claimant — same stack or another stack in
+ * the app — fails at synth instead of at CloudFormation deploy. Alias records
+ * claim their underlying Route53 type ("A"). Observation only: no constructs
+ * are created, so construct trees stay byte-identical.
+ */
+export declare function claimDnsRecord(construct: Construct, props: Pick<DnsRecordCommonProps, "zone" | "zoneName">, recordType: string, fqdn: string): void;
 export declare function applyDnsRecordTags(construct: Construct, props: Pick<DnsRecordCommonProps, "zoneName" | "costAllocationEnvironment" | "costAllocationDomain">): void;

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

@@ -1,16 +1,33 @@
 import { Duration } from "aws-cdk-lib";
-import { DNS_APEX } from "@fjall/util";
 import { applyCostAllocationTags } from "../../../../utils/costAllocationTags.js";
+import { registerDnsRecordClaim } from "../../../../utils/dnsRecordRegistry.js";
+// The record wrappers resolve their FQDN via the canonical BIND-semantics
+// resolver — the same function the patterns-layer domain validation calls —
+// re-exported here so the family keeps a single helper surface.
+export { resolveRecordFqdn } from "../../../../utils/domainTypes.js";
 export const DEFAULT_DNS_TTL_SECONDS = 300;
-export function resolveFqdn(zoneName, recordName) {
-    return recordName === DNS_APEX ? zoneName : `${recordName}.${zoneName}`;
-}
 export function resolveTtl(ttlSeconds) {
     return Duration.seconds(ttlSeconds ?? DEFAULT_DNS_TTL_SECONDS);
 }
 export function defaultDnsComment(recordType, fqdn) {
     return `Fjall-managed ${recordType} record for ${fqdn}`;
 }
+/**
+ * Claim the (zone, name, type) triple in the app-scoped collision registry
+ * (design D5, synth-side). Every wrapper in the dnsRecord family calls this
+ * from its constructor so a second claimant — same stack or another stack in
+ * the app — fails at synth instead of at CloudFormation deploy. Alias records
+ * claim their underlying Route53 type ("A"). Observation only: no constructs
+ * are created, so construct trees stay byte-identical.
+ */
+export function claimDnsRecord(construct, props, recordType, fqdn) {
+    registerDnsRecordClaim(construct, {
+        zone: props.zone,
+        zoneName: props.zoneName,
+        fqdn,
+        recordType
+    });
+}
 export function applyDnsRecordTags(construct, props) {
     applyCostAllocationTags(construct, {
         service: "dnsRecord",

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

@@ -1,14 +1,15 @@
 import { Construct } from "constructs";
 import { MxRecord as CdkMxRecord } from "aws-cdk-lib/aws-route53";
-import { applyDnsRecordTags, defaultDnsComment, resolveFqdn, resolveTtl } from "./dnsRecordBase.js";
+import { applyDnsRecordTags, claimDnsRecord, defaultDnsComment, resolveRecordFqdn, resolveTtl } from "./dnsRecordBase.js";
 export class MxRecord extends Construct {
     record;
     description;
     fqdn;
     constructor(scope, id, props) {
         super(scope, id);
-        this.fqdn = resolveFqdn(props.zoneName, props.recordName);
+        this.fqdn = resolveRecordFqdn(props.recordName, props.zoneName);
         this.description = props.description ?? defaultDnsComment("MX", this.fqdn);
+        claimDnsRecord(this, props, "MX", this.fqdn);
         this.record = new CdkMxRecord(this, "Record", {
             zone: props.zone,
             recordName: this.fqdn,

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

@@ -1,14 +1,15 @@
 import { Construct } from "constructs";
 import { NsRecord as CdkNsRecord } from "aws-cdk-lib/aws-route53";
-import { applyDnsRecordTags, defaultDnsComment, resolveFqdn, resolveTtl } from "./dnsRecordBase.js";
+import { applyDnsRecordTags, claimDnsRecord, defaultDnsComment, resolveRecordFqdn, resolveTtl } from "./dnsRecordBase.js";
 export class NsRecord extends Construct {
     record;
     description;
     fqdn;
     constructor(scope, id, props) {
         super(scope, id);
-        this.fqdn = resolveFqdn(props.zoneName, props.recordName);
+        this.fqdn = resolveRecordFqdn(props.recordName, props.zoneName);
         this.description = props.description ?? defaultDnsComment("NS", this.fqdn);
+        claimDnsRecord(this, props, "NS", this.fqdn);
         this.record = new CdkNsRecord(this, "Record", {
             zone: props.zone,
             recordName: this.fqdn,

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

@@ -1,14 +1,15 @@
 import { Construct } from "constructs";
 import { SrvRecord as CdkSrvRecord } from "aws-cdk-lib/aws-route53";
-import { applyDnsRecordTags, defaultDnsComment, resolveFqdn, resolveTtl } from "./dnsRecordBase.js";
+import { applyDnsRecordTags, claimDnsRecord, defaultDnsComment, resolveRecordFqdn, resolveTtl } from "./dnsRecordBase.js";
 export class SrvRecord extends Construct {
     record;
     description;
     fqdn;
     constructor(scope, id, props) {
         super(scope, id);
-        this.fqdn = resolveFqdn(props.zoneName, props.recordName);
+        this.fqdn = resolveRecordFqdn(props.recordName, props.zoneName);
         this.description = props.description ?? defaultDnsComment("SRV", this.fqdn);
+        claimDnsRecord(this, props, "SRV", this.fqdn);
         this.record = new CdkSrvRecord(this, "Record", {
             zone: props.zone,
             recordName: this.fqdn,

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

@@ -1,14 +1,15 @@
 import { Construct } from "constructs";
 import { TxtRecord as CdkTxtRecord } from "aws-cdk-lib/aws-route53";
-import { applyDnsRecordTags, defaultDnsComment, resolveFqdn, resolveTtl } from "./dnsRecordBase.js";
+import { applyDnsRecordTags, claimDnsRecord, defaultDnsComment, resolveRecordFqdn, resolveTtl } from "./dnsRecordBase.js";
 export class TxtRecord extends Construct {
     record;
     description;
     fqdn;
     constructor(scope, id, props) {
         super(scope, id);
-        this.fqdn = resolveFqdn(props.zoneName, props.recordName);
+        this.fqdn = resolveRecordFqdn(props.recordName, props.zoneName);
         this.description = props.description ?? defaultDnsComment("TXT", this.fqdn);
+        claimDnsRecord(this, props, "TXT", this.fqdn);
         this.record = new CdkTxtRecord(this, "Record", {
             zone: props.zone,
             recordName: this.fqdn,

package/dist/lib/resources/aws/networking/domainCertificate.d.ts

@@ -1,5 +1,5 @@
-import { Construct } from "constructs";
-import { type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
+import { type Construct } from "constructs";
+import { Certificate, type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
 import { type IHostedZone } from "aws-cdk-lib/aws-route53";
 export interface DomainCertificateProps {
     readonly domainName: string;
@@ -8,6 +8,15 @@ export interface DomainCertificateProps {
     readonly description?: string;
     readonly transparencyLogging?: boolean;
     readonly costAllocationEnvironment?: string;
+    /**
+     * Inherit the environment tag from an outer cascade (the fjall App's
+     * global tags) instead of stamping the "management" default when
+     * `costAllocationEnvironment` is not given. In-stack certificates minted
+     * inside an application (the ECS fallthrough mint) must set this: the
+     * cluster's app already tags the resolved environment tree-wide, and the
+     * resource-level default would out-tag it (deeper scope wins).
+     */
+    readonly inheritCostAllocationEnvironment?: boolean;
     readonly costAllocationDomain?: string;
     /**
      * Publish the `${domain}-certificate-arn` CloudFormation export. Default true.
@@ -17,9 +26,24 @@ export interface DomainCertificateProps {
      */
     readonly exportCertificateArn?: boolean;
 }
-export declare class DomainCertificate extends Construct {
+/**
+ * EXTENDS `Certificate` (subclass, not wrapper) so the underlying
+ * `AWS::CertificateManager::Certificate` synthesises at `<id>/Resource` — the
+ * byte-identical construct path, and therefore CFN logical ID, of a raw
+ * `new Certificate(scope, id)`. Wrapping a `Construct` around an inner
+ * `new Certificate(this, "Certificate")` would nest the resource one level
+ * deeper (`<id>/Certificate/Resource`), re-hash the logical ID, and make
+ * CloudFormation REPLACE a live in-use certificate on adoption (create new +
+ * flip listener + delete old) — exactly the churn the adoption design rules
+ * out ("same construct ID → zero cert churn"). Pinned by
+ * ecsDomainBaseline.test.ts and ecsNetworkingDomain.test.ts.
+ */
+export declare class DomainCertificate extends Certificate {
+    /**
+     * Self-alias kept for API compatibility with the wrapper era — consumers
+     * that read `.certificate` compile and behave unchanged.
+     */
     readonly certificate: ICertificate;
-    readonly certificateArn: string;
     readonly description: string;
     constructor(scope: Construct, id: string, props: DomainCertificateProps);
 }

package/dist/lib/resources/aws/networking/domainCertificate.js

@@ -1,30 +1,44 @@
-import { Construct } from "constructs";
 import { CfnOutput, Tags } from "aws-cdk-lib";
 import { Certificate, CertificateValidation } from "aws-cdk-lib/aws-certificatemanager";
 import { getDomainExportNames } from "@fjall/util";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
 import { applyCostAllocationTags } from "../../../utils/costAllocationTags.js";
-export class DomainCertificate extends Construct {
+/**
+ * EXTENDS `Certificate` (subclass, not wrapper) so the underlying
+ * `AWS::CertificateManager::Certificate` synthesises at `<id>/Resource` — the
+ * byte-identical construct path, and therefore CFN logical ID, of a raw
+ * `new Certificate(scope, id)`. Wrapping a `Construct` around an inner
+ * `new Certificate(this, "Certificate")` would nest the resource one level
+ * deeper (`<id>/Certificate/Resource`), re-hash the logical ID, and make
+ * CloudFormation REPLACE a live in-use certificate on adoption (create new +
+ * flip listener + delete old) — exactly the churn the adoption design rules
+ * out ("same construct ID → zero cert churn"). Pinned by
+ * ecsDomainBaseline.test.ts and ecsNetworkingDomain.test.ts.
+ */
+export class DomainCertificate extends Certificate {
+    /**
+     * Self-alias kept for API compatibility with the wrapper era — consumers
+     * that read `.certificate` compile and behave unchanged.
+     */
     certificate;
-    certificateArn;
     description;
     constructor(scope, id, props) {
-        super(scope, id);
-        this.description =
-            props.description ??
-                `Fjall-managed ACM certificate for ${props.domainName}`;
-        this.certificate = new Certificate(this, "Certificate", {
+        super(scope, id, {
             domainName: props.domainName,
             subjectAlternativeNames: props.subjectAlternativeNames,
             validation: CertificateValidation.fromDns(props.hostedZone),
             transparencyLoggingEnabled: props.transparencyLogging ?? true
         });
-        this.certificateArn = this.certificate.certificateArn;
+        this.certificate = this;
+        this.description =
+            props.description ??
+                `Fjall-managed ACM certificate for ${props.domainName}`;
         Tags.of(this).add("fjall:description", this.description);
         applyCostAllocationTags(this, {
             service: "certificate",
             domain: props.costAllocationDomain ?? props.domainName,
-            environment: props.costAllocationEnvironment
+            environment: props.costAllocationEnvironment,
+            inheritEnvironment: props.inheritCostAllocationEnvironment
         });
         if (props.exportCertificateArn !== false) {
             const safeKey = toPascalCase(props.domainName.split(".").join(""));

package/dist/lib/resources/aws/networking/hostedZone.d.ts

@@ -1,5 +1,6 @@
 import { Construct } from "constructs";
 import { type IHostedZone } from "aws-cdk-lib/aws-route53";
+import { type RemovalPolicyString } from "../messaging/utils.js";
 import { DelegationRole } from "../iam/delegationRole.js";
 import { type AwsStack } from "../base/awsStack.js";
 export interface HostedZoneProps {
@@ -10,6 +11,16 @@ export interface HostedZoneProps {
     readonly organisationIdExportName?: string;
     readonly costAllocationEnvironment?: string;
     readonly costAllocationDomain?: string;
+    /**
+     * Removal policy for the created zone (D4: zone safety). Default resolves
+     * via `envAwareRemovalPolicyDefault()` (production → RETAIN; other
+     * recognised stages → DESTROY; unrecognised values fail synth) — deleting
+     * a live zone dangles every parent/registrar delegation, so production
+     * zones survive stack destruction by default. The flip is metadata-only:
+     * the zone's logical ID is unaffected (flipless-retain-flip ADR). Ignored
+     * on the import path (`hostedZoneId` set), which manages no zone resource.
+     */
+    readonly removalPolicy?: RemovalPolicyString;
 }
 export interface HostedZoneFactoryImportOptions {
     readonly costAllocationEnvironment?: string;

package/dist/lib/resources/aws/networking/hostedZone.js

@@ -3,6 +3,7 @@ import { CfnOutput, Fn, Tags } from "aws-cdk-lib";
 import { HostedZone as AWSHostedZone } from "aws-cdk-lib/aws-route53";
 import { getDomainExportNames } from "@fjall/util";
 import { toPascalCase, getSafeZoneName } from "../../../utils/capitaliseString.js";
+import { envAwareRemovalPolicyDefault, toRemovalPolicy } from "../../../utils/removalPolicy.js";
 import { DelegationRole } from "../iam/delegationRole.js";
 import { applyCostAllocationTags } from "../../../utils/costAllocationTags.js";
 import { resolveOrgId } from "../../../utils/cdkContext.js";
@@ -39,6 +40,11 @@ export class HostedZone extends Construct {
                 zoneName: props.zoneName,
                 comment: this.description
             });
+            // D4 — resolved inside the create branch only: the env-aware default
+            // throws on unrecognised environments, and import-only synths manage
+            // no zone resource to police.
+            const removalPolicyValue = props.removalPolicy ?? envAwareRemovalPolicyDefault();
+            created.applyRemovalPolicy(toRemovalPolicy(removalPolicyValue));
             this.hostedZone = created;
             this.hostedZoneId = created.hostedZoneId;
             this.nameServers = created.hostedZoneNameServers

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

@@ -10,6 +10,15 @@ export interface CostAllocationTagsArgs {
     readonly service: string;
     readonly domain: string;
     readonly environment?: string;
+    /**
+     * When `environment` is not given, skip the environment tag at this scope
+     * entirely instead of stamping the "management" default, so an outer
+     * cascade (the fjall App's global tags carry the account-stage-resolved
+     * environment) provides it. Without this, the deeper-scope default wins
+     * CDK tag resolution and a production stack's resource is mis-tagged
+     * "management". An explicit `environment` always wins over inheritance.
+     */
+    readonly inheritEnvironment?: boolean;
     readonly owner?: string;
 }
 export declare function applyCostAllocationTags(scope: IConstruct, args: CostAllocationTagsArgs): void;

package/dist/lib/utils/costAllocationTags.js

@@ -7,7 +7,12 @@ export const COST_ALLOCATION_TAGS = {
 };
 export const DEFAULT_COST_ALLOCATION_ENVIRONMENT = "management";
 export function applyCostAllocationTags(scope, args) {
-    Tags.of(scope).add(COST_ALLOCATION_TAGS.ENVIRONMENT, args.environment ?? DEFAULT_COST_ALLOCATION_ENVIRONMENT);
+    if (args.environment !== undefined) {
+        Tags.of(scope).add(COST_ALLOCATION_TAGS.ENVIRONMENT, args.environment);
+    }
+    else if (args.inheritEnvironment !== true) {
+        Tags.of(scope).add(COST_ALLOCATION_TAGS.ENVIRONMENT, DEFAULT_COST_ALLOCATION_ENVIRONMENT);
+    }
     Tags.of(scope).add(COST_ALLOCATION_TAGS.SERVICE, args.service);
     Tags.of(scope).add(COST_ALLOCATION_TAGS.DOMAIN, args.domain);
     if (args.owner !== undefined) {

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

@@ -0,0 +1,52 @@
+import type { IHostedZone } from "aws-cdk-lib/aws-route53";
+import type { IConstruct } from "constructs";
+/**
+ * Synth-time DNS record-collision registry (design D5, synth-side half — the
+ * deploy-time preflight against live zones is Phase 2).
+ *
+ * Route53 allows exactly one record set per (zone, name, type); a second
+ * claimant today fails only at CloudFormation deploy with a raw "record set
+ * already exists". This registry makes the collision loud at synth: every
+ * construct in the dnsRecord wrapper family registers its claim here, and a
+ * duplicate claim throws naming both claimant construct paths and the cure.
+ *
+ * Scoping: claims are held per App (the construct-tree root), so multiple CDK
+ * Apps in one process — the vitest convention of a fresh `new CdkApp()` per
+ * test — never cross-talk, while stacks within one App share a claim table.
+ * Cross-stack duplicates inside one App are exactly the surface nothing
+ * catches before the change set executes.
+ *
+ * Lifecycle follows the manifest-collector precedent (manifestWriter.ts):
+ * module-level synth state with a reset hook, wired into
+ * `App.resetForTesting()` so the existing test-hygiene convention
+ * (resetForTesting + resetManifestCollector in beforeEach/afterEach) keeps
+ * working without a third per-test call.
+ */
+export interface DnsRecordClaim {
+    /** Zone the record lands in — consulted for identity resolution. */
+    readonly zone: IHostedZone;
+    /** Zone name as passed to the wrapper (identity fallback and error copy). */
+    readonly zoneName: string;
+    /** Fully-qualified record name the wrapper resolved. */
+    readonly fqdn: string;
+    /**
+     * Route53 record-set type. Alias records claim their underlying type ("A")
+     * — an alias and a plain A record on the same name are a real collision.
+     */
+    readonly recordType: string;
+}
+/**
+ * Register a record-set claim for `scope`, throwing when a DIFFERENT
+ * construct already claimed the same (zoneIdentity, recordName, recordType)
+ * triple within the same App. Re-registration by the same construct path
+ * (CDK aspects re-visiting, repeated synth) is idempotent. Pure observation:
+ * no constructs are created or mutated, so construct trees — including the
+ * eject-contract byte-identical composer IDs — are untouched.
+ */
+export declare function registerDnsRecordClaim(scope: IConstruct, claim: DnsRecordClaim): void;
+/**
+ * Reset all claims (for testing). Called by `App.resetForTesting()` alongside
+ * the App singleton reset so per-test App recycling starts clean — the
+ * manifest-collector lifecycle precedent.
+ */
+export declare function resetDnsRecordRegistry(): void;

package/dist/lib/utils/dnsRecordRegistry.js

@@ -0,0 +1,64 @@
+import { Token } from "aws-cdk-lib";
+/** Claims per App root: claim key → owning construct path. */
+let claimsByRoot = new WeakMap();
+/** Lowercase and strip the trailing dot — DNS names are case-insensitive. */
+function normaliseDnsName(name) {
+    return name.toLowerCase().replace(/\.$/, "");
+}
+/**
+ * Zone identity tolerates both literal zone IDs and zone names: prefer
+ * `hostedZoneId` when it is a known literal (imported or looked-up zones),
+ * else fall back to the lowercased zone name — zones created in-app carry an
+ * unresolved token ID that is meaningless as an identity.
+ */
+function resolveZoneIdentity(zone, zoneName) {
+    const hostedZoneId = zone.hostedZoneId;
+    if (hostedZoneId && !Token.isUnresolved(hostedZoneId)) {
+        return hostedZoneId;
+    }
+    return normaliseDnsName(zoneName);
+}
+/**
+ * Register a record-set claim for `scope`, throwing when a DIFFERENT
+ * construct already claimed the same (zoneIdentity, recordName, recordType)
+ * triple within the same App. Re-registration by the same construct path
+ * (CDK aspects re-visiting, repeated synth) is idempotent. Pure observation:
+ * no constructs are created or mutated, so construct trees — including the
+ * eject-contract byte-identical composer IDs — are untouched.
+ */
+export function registerDnsRecordClaim(scope, claim) {
+    const root = scope.node.root;
+    let claims = claimsByRoot.get(root);
+    if (!claims) {
+        claims = new Map();
+        claimsByRoot.set(root, claims);
+    }
+    const recordType = claim.recordType.toUpperCase();
+    const key = [
+        resolveZoneIdentity(claim.zone, claim.zoneName),
+        normaliseDnsName(claim.fqdn),
+        recordType
+    ].join("|");
+    const claimantPath = scope.node.path;
+    const existing = claims.get(key);
+    if (existing === undefined) {
+        claims.set(key, claimantPath);
+        return;
+    }
+    if (existing === claimantPath) {
+        return;
+    }
+    throw new Error(`DNS record '${claim.fqdn}' (${recordType}) in zone '${claim.zoneName}': ` +
+        `already claimed by construct '${existing}' — duplicate claim by '${claimantPath}'. ` +
+        `Route53 allows one record set per (zone, name, type); CloudFormation would reject this at deploy. ` +
+        `Keep one owner per record — satellites own their app records; the domain stack owns zone-level records. ` +
+        `Remove or rename one claimant, or run 'fjall domain records list ${claim.zoneName}' to inspect the zone.`);
+}
+/**
+ * Reset all claims (for testing). Called by `App.resetForTesting()` alongside
+ * the App singleton reset so per-test App recycling starts clean — the
+ * manifest-collector lifecycle precedent.
+ */
+export function resetDnsRecordRegistry() {
+    claimsByRoot = new WeakMap();
+}

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

@@ -1,36 +1,43 @@
-export { DNS_APEX, getDomainExportNames, type ManagedDomainExports } from "@fjall/util";
-export interface DnsRecordInput {
-    type: "A" | "AAAA" | "CNAME" | "MX" | "TXT" | "NS" | "SRV" | "CAA";
-    name: string;
-    value: string;
-    ttl?: number;
-    priority?: number;
-    weight?: number;
-    port?: number;
-}
-export interface DelegationInput {
-    subdomain: string;
-    targetAccount: string;
-}
-export interface CertificateInput {
-    domainName: string;
-    subjectAlternativeNames?: string[];
-}
-export interface DomainApexProps {
-    type: "domain";
-    zoneName: string;
-    records?: DnsRecordInput[];
-    delegations?: DelegationInput[];
-    certificates?: CertificateInput[];
-    hostedZoneId?: string;
-}
-export interface DomainDelegatedProps {
-    type: "delegated";
-    zoneName: string;
-    parentZoneName: string;
-    parentAccountName: string;
-    records?: DnsRecordInput[];
-    certificates?: CertificateInput[];
-}
-export type IDomainProps = DomainApexProps | DomainDelegatedProps;
-export declare const ALIAS_CDK_PREFIX: "ALIAS:";
+export { DNS_APEX, getDomainExportNames, isManagedDomainBinding, type ManagedDomainBinding, type ManagedDomainExports } from "@fjall/util";
+/**
+ * Dot-boundary suffix matching. Rejects pathological cases where a user-supplied
+ * zone appears as a suffix of another zone (e.g. 'evilexample.com' against
+ * zone 'example.com' — `endsWith('example.com')` returns true without the
+ * leading dot). Shared by the patterns-layer domain validation and the
+ * resources-layer ECS networking (lowest common layer per generator-standards
+ * § Infrastructure Layer Boundaries).
+ */
+export declare function isWithinZone(candidate: string, zoneName: string): boolean;
+/**
+ * Canonical BIND-semantics resolver for DNS record names — the single
+ * authority shared by the patterns-layer domain validation and the
+ * resources-layer dnsRecord family (lowest common layer per
+ * generator-standards § Infrastructure Layer Boundaries). Contract:
+ *
+ * - `'@'` — the zone apex; resolves to the zone name.
+ * - Trailing dot — an absolute FQDN; must equal the zone or end with
+ *   `.<zone>.`, otherwise the name belongs to another zone and is rejected.
+ *   The conventional trailing dot is shed on return because CloudFormation
+ *   RecordSet names carry none at this layer (CDK re-appends it).
+ * - No trailing dot — relative to the zone regardless of label count
+ *   (`www` and `s1._domainkey` alike); the zone is appended exactly once.
+ * - A dotless name that already ends with the bare zone is ambiguous between
+ *   the relative and absolute readings and is rejected, naming both honest
+ *   spellings.
+ */
+export declare function resolveRecordFqdn(recordName: string, zoneName: string): string;
+/**
+ * Two-step deploy phase for constructs whose certificates must not be issued
+ * before their zone's NS delegation has propagated (design R2 cert-hang
+ * guard). `"zone"` synthesises the hosted zone (+ delegation record) only;
+ * `"full"` additionally issues certificates. Shared by the delegated `Domain`
+ * topology and `DevSubstrate` — lowest common layer per generator-standards
+ * § Infrastructure Layer Boundaries.
+ */
+export type DomainDeployPhase = "zone" | "full";
+/**
+ * Default deploy phase when `phase` is omitted — the complete build. The
+ * two-step guard (R2) sets `"zone"` explicitly for step 1, so the safe
+ * default for a single-shot deploy is everything.
+ */
+export declare const DOMAIN_DEPLOY_DEFAULT_PHASE: DomainDeployPhase;

package/dist/lib/utils/domainTypes.js

@@ -1,2 +1,65 @@
-export { DNS_APEX, getDomainExportNames } from "@fjall/util";
-export const ALIAS_CDK_PREFIX = "ALIAS:";
+import { DNS_APEX } from "@fjall/util";
+export { DNS_APEX, getDomainExportNames, isManagedDomainBinding } from "@fjall/util";
+/**
+ * Dot-boundary suffix matching. Rejects pathological cases where a user-supplied
+ * zone appears as a suffix of another zone (e.g. 'evilexample.com' against
+ * zone 'example.com' — `endsWith('example.com')` returns true without the
+ * leading dot). Shared by the patterns-layer domain validation and the
+ * resources-layer ECS networking (lowest common layer per generator-standards
+ * § Infrastructure Layer Boundaries).
+ */
+export function isWithinZone(candidate, zoneName) {
+    if (candidate === zoneName) {
+        return true;
+    }
+    return candidate.endsWith(`.${zoneName}`);
+}
+/**
+ * Canonical BIND-semantics resolver for DNS record names — the single
+ * authority shared by the patterns-layer domain validation and the
+ * resources-layer dnsRecord family (lowest common layer per
+ * generator-standards § Infrastructure Layer Boundaries). Contract:
+ *
+ * - `'@'` — the zone apex; resolves to the zone name.
+ * - Trailing dot — an absolute FQDN; must equal the zone or end with
+ *   `.<zone>.`, otherwise the name belongs to another zone and is rejected.
+ *   The conventional trailing dot is shed on return because CloudFormation
+ *   RecordSet names carry none at this layer (CDK re-appends it).
+ * - No trailing dot — relative to the zone regardless of label count
+ *   (`www` and `s1._domainkey` alike); the zone is appended exactly once.
+ * - A dotless name that already ends with the bare zone is ambiguous between
+ *   the relative and absolute readings and is rejected, naming both honest
+ *   spellings.
+ */
+export function resolveRecordFqdn(recordName, zoneName) {
+    if (recordName === DNS_APEX) {
+        return zoneName;
+    }
+    if (recordName.endsWith(".")) {
+        const absolute = recordName.slice(0, -1);
+        if (absolute !== zoneName && !absolute.endsWith(`.${zoneName}`)) {
+            throw new Error(`DNS record name '${recordName}' is absolute (trailing dot) but ` +
+                `lies outside zone '${zoneName}'. Cure: an absolute name must be ` +
+                `'${zoneName}.' or end with '.${zoneName}.'; records for another ` +
+                `zone belong on that zone's own Domain construct.`);
+        }
+        return absolute;
+    }
+    if (recordName === zoneName || recordName.endsWith(`.${zoneName}`)) {
+        const relativeSpelling = recordName === zoneName
+            ? DNS_APEX
+            : recordName.slice(0, -(zoneName.length + 1));
+        throw new Error(`DNS record name '${recordName}' ends with zone '${zoneName}' but has ` +
+            `no trailing dot, so it is ambiguous between relative ` +
+            `('${recordName}.${zoneName}') and absolute ('${recordName}'). ` +
+            `Cure: spell it '${relativeSpelling}' (relative to the zone) or ` +
+            `'${recordName}.' (absolute).`);
+    }
+    return `${recordName}.${zoneName}`;
+}
+/**
+ * Default deploy phase when `phase` is omitted — the complete build. The
+ * two-step guard (R2) sets `"zone"` explicitly for step 1, so the safe
+ * default for a single-shot deploy is everything.
+ */
+export const DOMAIN_DEPLOY_DEFAULT_PHASE = "full";

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

@@ -0,0 +1,37 @@
+/**
+ * CDK-context channel for CLI-injected managed-domain bindings (design
+ * 2026-07-17 domain-management gold-plating, D2 — resolution by injection).
+ *
+ * At deploy time the Fjall CLI resolves each app-consumed domain against the
+ * declared `fjall/domains/` components (DescribeStacks on the domain stack)
+ * and injects one context entry per zone:
+ *
+ *   -c fjall:managedDomain:<zoneName>=<JSON ManagedDomainBinding>
+ *
+ * (emitter: deploy-core `CdkArgumentBuilder.buildContextArgs` — keep the
+ * prefix literal in sync). Constructs read the entry ahead of their BYO
+ * `zoneName`/`hostedZone` props; an EXPLICIT `managedDomain` prop still wins
+ * over the injected value. Bare-CDK synth simply lacks the context and falls
+ * back to explicit props.
+ *
+ * Utils layer on purpose: consumed by both the resources layer
+ * (`ecsNetworking.addHostedZone`) and the patterns layer
+ * (`patternDomain.resolvePatternZone`), and utils is their lowest common
+ * layer (generator-standards § Infrastructure Layer Boundaries).
+ */
+import type { Node } from "constructs";
+import type { ManagedDomainBinding } from "@fjall/util";
+export declare const MANAGED_DOMAIN_CONTEXT_PREFIX: "fjall:managedDomain:";
+export declare function getManagedDomainContextKey(zoneName: string): string;
+/**
+ * Read the CLI-injected {@link ManagedDomainBinding} for `domainName`,
+ * walking exact → parent zones (mirroring the CLI's
+ * `DomainService.matchManagedDomain` semantics: `app.example.com` matches a
+ * binding injected for `example.com`). Returns undefined when no entry is
+ * present (bare-CDK synth); throws a context-prefixed, value-echoing,
+ * cure-naming error when an entry exists but is malformed — a corrupt
+ * binding must fail the synth, never fall through to a guessed zone.
+ *
+ * `context` prefixes every error, e.g. `Static site 'marketing'`.
+ */
+export declare function readInjectedManagedDomainBinding(node: Node, domainName: string, context: string): ManagedDomainBinding | undefined;