@fjall/components-infrastructure 2.33.0 → 3.0.0

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

@@ -24,6 +24,7 @@ import { CrossAccountDelegationRecord } from "../../resources/aws/networking/cro
 import { DomainCertificate } from "../../resources/aws/networking/domainCertificate.js";
 import { Role } from "../../resources/aws/iam/role.js";
 import { toPascalCase } from "../../utils/capitaliseString.js";
+import { DOMAIN_DEPLOY_DEFAULT_PHASE } from "../../utils/domainTypes.js";
 import { DEV_AURORA_DEFAULTS } from "../../resources/aws/database/rdsDefaults.js";
 import { DEV_APP_TAG_KEY, DEV_TAG_KEY, DEV_TAG_VALUE } from "../../utils/devSubstrateTags.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -54,12 +55,11 @@ const DEV_SUBSTRATE_PARENT_ROLE_ID = "DevSubstrateParentDelegationRole";
 /** Construct ids for the substrate's wildcard cert + :443 HTTPS listener (A6). */
 const DEV_SUBSTRATE_CERT_ID = "DevSubstrateCertificate";
 const DEV_SUBSTRATE_HTTPS_LISTENER_ID = "DevSubstrateHttpsListener";
-/**
- * Default deploy phase when `phase` is omitted — the cert + :443 listener build.
- * The two-step guard (design R2) sets `"zone"` explicitly for step 1, so the
- * safe default for a single-shot deploy is the complete substrate.
- */
-const DEV_SUBSTRATE_DEFAULT_PHASE = "full";
+// Default deploy phase when `phase` is omitted — the cert + :443 listener
+// build. Shared with the delegated `Domain` topology via
+// `DOMAIN_DEPLOY_DEFAULT_PHASE` (utils/domainTypes.ts): the R2 two-step guard
+// sets `"zone"` explicitly for step 1, so the safe default for a single-shot
+// deploy is the complete substrate.
 /**
  * The substrate's database mode, surfaced to slot-ops as an export so the
  * hand-created G2 slot knows whether to wire Aurora Data-API creds or a
@@ -142,6 +142,11 @@ export class DevSubstrate extends Construct {
             // exposes for the cluster ARN; it returns databaseCluster.clusterArn.
             dbClusterArn: database.getSnapshotTarget().arn,
             dbSecretArn: database.getCredentials().secret.secretArn,
+            // Proxy-less substrate ⇒ getHostEndpoint() is the cluster writer endpoint;
+            // it + the port ride the exports because the dev role cannot rds:Describe*
+            // at runtime to resolve them.
+            dbWriterEndpoint: database.getHostEndpoint(),
+            dbPort: database.getHostPort(),
             slotExecutionRoleArn: slotExecutionRole.roleArn,
             slotRepositoryUri: slotRepository.repositoryUri,
             wakerTargetGroupArn: wakerTargetGroup.targetGroupArn,
@@ -244,7 +249,10 @@ export class DevSubstrate extends Construct {
         // fence-pinned name — the reaper finds it by the subtree fence tags. A pinned
         // name would only reintroduce the 32-char ALB-name truncation dance.
         const loadBalancer = createApplicationLoadBalancer(this, DEV_SUBSTRATE_ALB_ID, { vpc, internetFacing: true, securityGroup: albSecurityGroup });
-        slotSecurityGroup.connections.allowFrom(albSecurityGroup, Port.tcp(DEV_SUBSTRATE_SLOT_PORT), "Dev substrate ALB → slot tasks");
+        slotSecurityGroup.connections.allowFrom(albSecurityGroup, Port.tcp(DEV_SUBSTRATE_SLOT_PORT), 
+        // EC2 SG-rule descriptions reject non-ASCII (allowed set is
+        // `a-zA-Z0-9. _-:/()#,@[]+=&;{}!$*` — no arrow, em-dash, or even `>`).
+        "Dev substrate ALB to slot tasks");
         // Unconditional 404 default — the substrate's only routes are per-slot
         // host-header rules, so an unmatched host must 404, never fall through (the ECS
         // path's 404 is conditional on >=2 routes). The :443 listener + wildcard cert
@@ -327,7 +335,7 @@ export class DevSubstrate extends Construct {
         }
         // Step 2 of the R2 two-step gate: synthesising the cert before the step-1 NS
         // has propagated hangs ACM DNS-validation for hours, so "zone" stops here.
-        if ((props.phase ?? DEV_SUBSTRATE_DEFAULT_PHASE) !== "full")
+        if ((props.phase ?? DOMAIN_DEPLOY_DEFAULT_PHASE) !== "full")
             return { devDomain: childZoneName };
         // exportCertificateArn:false — consumed in-stack by the :443 listener (slots
         // reference the exported LISTENER arn, not the cert), and the wildcard `*.`
@@ -375,6 +383,8 @@ export class DevSubstrate extends Construct {
         emit(this, "AlbCloudWatchName", values.albCloudWatchName);
         emit(databaseScope, "DbClusterArn", values.dbClusterArn);
         emit(databaseScope, "DbSecretArn", values.dbSecretArn);
+        emit(databaseScope, "DbWriterEndpoint", values.dbWriterEndpoint);
+        emit(databaseScope, "DbPort", values.dbPort);
         emit(this, "SlotExecutionRoleArn", values.slotExecutionRoleArn);
         emit(this, "SlotRepositoryUri", values.slotRepositoryUri);
         emit(this, "WakerTargetGroupArn", values.wakerTargetGroupArn);

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

@@ -1,15 +1,8 @@
 import type { Construct } from "constructs";
 import type { IHostedZone } from "aws-cdk-lib/aws-route53";
-import type { DnsRecord, DnsRecordInput } from "./interfaces/domain.js";
+import type { DnsRecord } from "./interfaces/domain.js";
 /**
- * Legacy composer consumed by `DomainFactory` (deleted in Phase 2). Accepts
- * the `DnsRecordInput` shape from the BIND-primary era where ALIAS sentinels
- * live in `value`. Typed targets are not supported here; use
- * `composeTypedDnsRecords` instead.
- */
-export declare function composeDnsRecords(scope: Construct, zone: IHostedZone, zoneName: string, records: DnsRecordInput[]): void;
-/**
- * Typed composer consumed by the new `Domain` construct. Accepts the
+ * Typed composer consumed by the `Domain` construct. Accepts the
  * discriminated `DnsRecord` union (`StandardRecord | AliasRecord`).
  *
  * `AliasRecord` entries MUST carry a `target` produced by `fjallApp()`,

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

@@ -1,105 +1,13 @@
 import { CaaTag } from "aws-cdk-lib/aws-route53";
 import { ARecord, AaaaRecord, AliasRecord, CnameRecord, MxRecord, TxtRecord, NsRecord, SrvRecord, CaaRecord } from "../../resources/aws/networking/dnsRecord/index.js";
 import { toPascalCase, getSafeZoneName } from "../../utils/capitaliseString.js";
-import { ALIAS_CDK_PREFIX } from "../../utils/domainTypes.js";
 import { DNS_APEX } from "@fjall/util";
+// H13: the legacy BIND-era `composeDnsRecords` (untyped `DnsRecordInput` with
+// ALIAS sentinels in `value`) was deleted in Phase 2. The typed composer below
+// deliberately preserves its construct-id formula — see the eject-contract
+// note on `composeTypedDnsRecords`.
 /**
- * Legacy composer consumed by `DomainFactory` (deleted in Phase 2). Accepts
- * the `DnsRecordInput` shape from the BIND-primary era where ALIAS sentinels
- * live in `value`. Typed targets are not supported here; use
- * `composeTypedDnsRecords` instead.
- */
-export function composeDnsRecords(scope, zone, zoneName, records) {
-    const safeZone = toPascalCase(getSafeZoneName(zoneName));
-    records.forEach((record, index) => {
-        // Skip alias sentinels — they are resolved via the typed path in Phase 1+.
-        if (record.value.startsWith(ALIAS_CDK_PREFIX)) {
-            return;
-        }
-        const safeName = toPascalCase(record.name === DNS_APEX ? "Apex" : record.name);
-        const constructId = `${safeZone}${safeName}${record.type}Record${index}`;
-        const common = {
-            zone,
-            zoneName,
-            recordName: record.name,
-            ttl: record.ttl
-        };
-        switch (record.type) {
-            case "A":
-                new ARecord(scope, constructId, {
-                    ...common,
-                    values: [record.value]
-                });
-                break;
-            case "AAAA":
-                new AaaaRecord(scope, constructId, {
-                    ...common,
-                    values: [record.value]
-                });
-                break;
-            case "CNAME":
-                new CnameRecord(scope, constructId, {
-                    ...common,
-                    domainName: record.value
-                });
-                break;
-            case "MX":
-                new MxRecord(scope, constructId, {
-                    ...common,
-                    values: [
-                        {
-                            hostName: record.value,
-                            priority: record.priority ?? 10
-                        }
-                    ]
-                });
-                break;
-            case "TXT":
-                new TxtRecord(scope, constructId, {
-                    ...common,
-                    values: [record.value]
-                });
-                break;
-            case "NS":
-                new NsRecord(scope, constructId, {
-                    ...common,
-                    values: [record.value]
-                });
-                break;
-            case "SRV":
-                new SrvRecord(scope, constructId, {
-                    ...common,
-                    values: [
-                        {
-                            hostName: record.value,
-                            priority: record.priority ?? 10,
-                            weight: record.weight ?? 0,
-                            port: record.port ?? 443
-                        }
-                    ]
-                });
-                break;
-            case "CAA":
-                new CaaRecord(scope, constructId, {
-                    ...common,
-                    values: [
-                        {
-                            flag: 0,
-                            tag: record.value.includes("issuewild")
-                                ? CaaTag.ISSUEWILD
-                                : record.value.includes("iodef")
-                                    ? CaaTag.IODEF
-                                    : CaaTag.ISSUE,
-                            value: record.value
-                        }
-                    ]
-                });
-                break;
-        }
-    });
-}
-/**
- * Typed composer consumed by the new `Domain` construct. Accepts the
+ * Typed composer consumed by the `Domain` construct. Accepts the
  * discriminated `DnsRecord` union (`StandardRecord | AliasRecord`).
  *
  * `AliasRecord` entries MUST carry a `target` produced by `fjallApp()`,

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

@@ -7,8 +7,9 @@ import type { DomainProps, ManualRecord } from "./interfaces/domain.js";
  * User-facing Route53-oriented domain construct. Dispatches on
  * `props.registrar` to one of three per-registrar patterns:
  *
- *   - `route53` → `composeApexDomain` (apex HZ + delegations)
- *   - `external-delegated` → `composeDelegatedDomain` (sub-HZ only)
+ *   - `route53` → `composeApexDomain` (apex HZ + org-gated DelegationRole)
+ *   - `external-delegated` → `composeDelegatedDomain` (sub-HZ; D8
+ *     child-writes NS delegation via `parentDelegationRoleArn`)
  *   - `external-records` → `composeExternalRecords` (no HZ, manual records)
  *
  * Applies gold-plating tags (`fjall:description`, three

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

@@ -11,8 +11,9 @@ import { applyCostAllocationTags } from "../../utils/costAllocationTags.js";
  * User-facing Route53-oriented domain construct. Dispatches on
  * `props.registrar` to one of three per-registrar patterns:
  *
- *   - `route53` → `composeApexDomain` (apex HZ + delegations)
- *   - `external-delegated` → `composeDelegatedDomain` (sub-HZ only)
+ *   - `route53` → `composeApexDomain` (apex HZ + org-gated DelegationRole)
+ *   - `external-delegated` → `composeDelegatedDomain` (sub-HZ; D8
+ *     child-writes NS delegation via `parentDelegationRoleArn`)
  *   - `external-records` → `composeExternalRecords` (no HZ, manual records)
  *
  * Applies gold-plating tags (`fjall:description`, three

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

@@ -1,10 +1,12 @@
-import { Annotations } from "aws-cdk-lib";
+import { Annotations, Token } from "aws-cdk-lib";
 import { DNS_APEX } from "@fjall/util";
+import { isWithinZone, resolveRecordFqdn } from "../../utils/domainTypes.js";
 const VALID_REGISTRARS = [
     "route53",
     "external-delegated",
     "external-records"
 ];
+const VALID_PHASES = ["zone", "full"];
 /**
  * Synchronous synth-time validator for `DomainProps`. Throws on hard errors
  * (CDK catches and surfaces the stack trace pointing at the `new Domain(...)`
@@ -18,7 +20,7 @@ export function validateDomainProps(scope, props) {
     const effectiveZone = resolveEffectiveZoneName(props);
     validateRecords(scope, props, effectiveZone);
     validateCertificates(props, effectiveZone);
-    validateDelegations(props);
+    validateDelegationConfig(props);
 }
 function validateRegistrar(props) {
     const registrar = props.registrar;
@@ -26,11 +28,15 @@ function validateRegistrar(props) {
         !VALID_REGISTRARS.includes(registrar)) {
         throw new Error(`Domain registrar must be one of ${VALID_REGISTRARS.join(", ")}; received: ${String(registrar)}`);
     }
-    // Runtime defence — TS forbids `delegations` on external-records, but a JS
-    // caller could still pass it. Surface the mistake loudly.
-    if (registrar === "external-records" &&
-        props.delegations !== undefined) {
-        throw new Error("Domain: 'delegations' is not supported with registrar: 'external-records' — there is no Fjall-managed hosted zone to cascade from.");
+    // D8/D12 removed-surface defence — the parent-writes `delegations[]` prop
+    // no longer exists on any registrar. TS already rejects it; this catches JS
+    // callers and stale generated code, naming the replacement.
+    if (props.delegations !== undefined) {
+        throw new Error("Domain: 'delegations' was removed (D8 — one delegation direction, child " +
+            "writes NS). Cure: declare the delegated child as its own Domain with " +
+            "registrar: 'external-delegated' and set 'parentDelegationRoleArn' " +
+            "(the CLI injects it via ManagedDomainBinding.delegationRoleArn); the " +
+            "child then UPSERTs its NS records into this zone.");
     }
 }
 function resolveEffectiveZoneName(props) {
@@ -47,10 +53,9 @@ function validateRecords(scope, props, effectiveZone) {
     const records = props.records ?? [];
     const seen = new Map();
     for (const record of records) {
-        const fqdn = recordFqdn(record.name, effectiveZone);
-        if (!isWithinZone(fqdn, effectiveZone)) {
-            throw new Error(`Record '${fqdn}' falls outside managed zone '${effectiveZone}'. Use a separate Domain construct or a SubdomainDelegation.`);
-        }
+        // Rejects wrong-zone absolute names and ambiguous bare-zone-suffixed
+        // names itself; a resolved name is therefore always within the zone.
+        const fqdn = resolveRecordFqdn(record.name, effectiveZone);
         if ("target" in record) {
             if (record.name === DNS_APEX && props.registrar === "external-records") {
                 throw new Error("Apex A records with Fjall targets require registrar: 'route53' or 'external-delegated' because RFC 1035 forbids CNAME at apex. Use a subdomain or change registrar.");
@@ -89,19 +94,61 @@ function validateCertificates(props, effectiveZone) {
         }
     }
 }
-function validateDelegations(props) {
-    if (props.registrar === "external-records") {
+/**
+ * D8 delegation-consistency checks for the child-writes shape.
+ *
+ * `parentDelegationRoleArn` and `phase` belong to the delegated topology
+ * (`external-delegated`) only; on any other registrar their presence is a
+ * hard error rather than a silent no-op. On the delegated topology the role
+ * ARN must be a LITERAL string (VD2-a): an unresolved token means the caller
+ * reached for `Fn.importValue`, which resolves same-account only and is
+ * exactly the trap that sank the legacy `DomainDelegation` pattern.
+ */
+function validateDelegationConfig(props) {
+    const arn = props
+        .parentDelegationRoleArn;
+    const phase = props.phase;
+    if (props.registrar !== "external-delegated") {
+        if (arn !== undefined) {
+            throw new Error(`Domain: 'parentDelegationRoleArn' is only supported with registrar: ` +
+                `'external-delegated' (received registrar: '${props.registrar}'). ` +
+                `Cure: the delegated child zone declares it — move the prop onto ` +
+                `the child Domain, or drop it.`);
+        }
+        if (phase !== undefined) {
+            throw new Error(`Domain: 'phase' is only supported with registrar: ` +
+                `'external-delegated' (received registrar: '${props.registrar}'). ` +
+                `Cure: drop the prop — only delegated child zones need the ` +
+                `two-step zone→full deploy gate.`);
+        }
         return;
     }
-    const delegations = props
-        .delegations;
-    if (!delegations) {
+    if (phase !== undefined &&
+        !VALID_PHASES.includes(phase)) {
+        throw new Error(`Domain: 'phase' must be one of ${VALID_PHASES.map((p) => `'${p}'`).join(", ")}; ` +
+            `received: '${String(phase)}'. Cure: use 'zone' for step 1 of the ` +
+            `two-step delegated deploy, 'full' (or omit) for the complete build.`);
+    }
+    if (arn === undefined) {
         return;
     }
-    for (const delegation of delegations) {
-        if (delegation.auto === true && !delegation.toAccount) {
-            throw new Error(`Delegation '${delegation.subdomain}' has auto: true but no 'toAccount' set. Provide the child Fjall account name.`);
-        }
+    if (typeof arn !== "string") {
+        throw new Error(`Domain: 'parentDelegationRoleArn' must be a string; received: ` +
+            `${typeof arn}. Cure: pass the parent DelegationRole ARN as a ` +
+            `literal string.`);
+    }
+    if (Token.isUnresolved(arn)) {
+        throw new Error("Domain: 'parentDelegationRoleArn' is an unresolved token (e.g. " +
+            "Fn.importValue) — cross-account delegation requires a literal role " +
+            "ARN because Fn::ImportValue resolves same-account only (VD2-a). " +
+            "Cure: deploy via the Fjall CLI, which injects the literal ARN from " +
+            "ManagedDomainBinding.delegationRoleArn, or paste the parent zone's " +
+            "DelegationRoleArn output value directly.");
+    }
+    if (!/^arn:[^:]+:iam::\d{12}:role\/.+$/.test(arn)) {
+        throw new Error(`Domain: 'parentDelegationRoleArn' does not look like an IAM role ARN; ` +
+            `received: '${arn}'. Cure: pass the parent zone's DelegationRoleArn ` +
+            `output (arn:<partition>:iam::<account>:role/<name>).`);
     }
 }
 function normaliseCertificate(cert) {
@@ -113,33 +160,11 @@ function normaliseCertificate(cert) {
         subjectAlternativeNames: cert.subjectAlternativeNames
     };
 }
-function recordFqdn(recordName, zoneName) {
-    if (recordName === DNS_APEX) {
-        return zoneName;
-    }
-    // A user may already provide a FQDN (e.g. "api.example.com") or a single
-    // label ("api"). If the name contains a dot, treat it as an FQDN — the
-    // zone-boundary check then decides whether it is within the managed zone.
-    // A bare label is always appended to the zone.
-    if (recordName.includes(".")) {
-        return recordName;
-    }
-    return `${recordName}.${zoneName}`;
-}
 function assertWithinZone(candidate, zoneName) {
     if (!isWithinZone(candidate, zoneName)) {
-        throw new Error(`'${candidate}' falls outside managed zone '${zoneName}'. Use a separate Domain construct or a SubdomainDelegation.`);
-    }
-}
-/**
- * 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).
- */
-function isWithinZone(candidate, zoneName) {
-    if (candidate === zoneName) {
-        return true;
+        throw new Error(`'${candidate}' falls outside managed zone '${zoneName}'. Use a separate Domain construct or a delegated child Domain (registrar: 'external-delegated').`);
     }
-    return candidate.endsWith(`.${zoneName}`);
 }
+// isWithinZone (dot-boundary suffix matching) and resolveRecordFqdn (the
+// canonical BIND-semantics record-name resolver) live in
+// lib/utils/domainTypes.ts — shared with the resources-layer dnsRecord family.

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

@@ -2,7 +2,7 @@ import { CfnOutput } from "aws-cdk-lib";
 import { Certificate as AcmCertificate, CertificateValidation } from "aws-cdk-lib/aws-certificatemanager";
 import { resolveTargetToDnsName } from "./targets/targetResolution.js";
 import { toPascalCase, getSafeZoneName } from "../../utils/capitaliseString.js";
-import { DNS_APEX } from "@fjall/util";
+import { resolveRecordFqdn } from "../../utils/domainTypes.js";
 const MANUAL_RECORD_TTL_SECONDS = 300;
 /**
  * Composition for `registrar: "external-records"`. No Route53 hosted zone is
@@ -60,7 +60,7 @@ export function composeExternalRecords(scope, props) {
     //    entries.
     const records = props.records ?? [];
     records.forEach((record, index) => {
-        const fqdn = toFqdn(record.name, props.zoneName);
+        const fqdn = resolveRecordFqdn(record.name, props.zoneName);
         if ("target" in record) {
             const value = resolveTargetToDnsName(record.target);
             const manual = {
@@ -98,15 +98,6 @@ function normaliseCertificate(cert) {
         transparencyLogging: cert.transparencyLogging
     };
 }
-function toFqdn(recordName, zoneName) {
-    if (recordName === DNS_APEX) {
-        return zoneName;
-    }
-    if (recordName === zoneName || recordName.endsWith(`.${zoneName}`)) {
-        return recordName;
-    }
-    return `${recordName}.${zoneName}`;
-}
 function narrowManualType(type) {
     switch (type) {
         case "A":

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

@@ -7,11 +7,9 @@ export * from "./fivetranProxy.js";
 export * from "./database.js";
 export * from "../../resources/aws/compute/ec2.js";
 export * from "../../resources/aws/networking/hostedZone.js";
-export * from "./domainFactory.js";
-export * from "./domainDelegation.js";
 export { Domain } from "./domain.js";
 export * from "./targets/index.js";
-export { getDomainExportNames, type DnsRecordInput, type DelegationInput, type CertificateInput, type DomainApexProps, type DomainDelegatedProps, type IDomainProps, type ManagedDomainExports, type FjallTarget, type StandardRecord, type DnsRecord, type Certificate, type SubdomainDelegation, type DomainCommonProps, type Route53ApexProps, type ExternalDelegatedProps, type ExternalRecordsProps, type DomainProps, type ManualRecord } from "./interfaces/domain.js";
+export { getDomainExportNames, type ManagedDomainExports, type DomainDeployPhase, type FjallTarget, type StandardRecord, type DnsRecord, type Certificate, type DomainCommonProps, type Route53ApexProps, type ExternalDelegatedProps, type ExternalRecordsProps, type DomainProps, type ManualRecord } from "./interfaces/domain.js";
 export { MIGRATION_SNAPSHOT_NAME_PREFIX, EXPECTED_SCHEMA_VERSION_ENV, EXPECTED_SCHEMA_VERSION_TOOL_ENV } from "./interfaces/database.js";
 export * from "./compute.js";
 export * from "./storage.js";

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

@@ -9,9 +9,8 @@ export * from "./database.js";
 // Resource-layer re-exports — consumed by patterns that compose these primitives
 export * from "../../resources/aws/compute/ec2.js";
 export * from "../../resources/aws/networking/hostedZone.js";
-// Domain patterns
-export * from "./domainFactory.js";
-export * from "./domainDelegation.js";
+// Domain patterns (H13: the legacy DomainFactory/ApexDomain/DomainDelegation
+// layer was deleted in Phase 2 — `Domain` is the only construct surface).
 export { Domain } from "./domain.js";
 export * from "./targets/index.js";
 // Explicit exports from the interfaces barrel — avoids collision between the

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

@@ -1,4 +1,5 @@
-export type { DnsRecordInput, DelegationInput, CertificateInput, DomainApexProps, DomainDelegatedProps, IDomainProps, ManagedDomainExports } from "../../../utils/domainTypes.js";
+import type { DomainDeployPhase } from "../../../utils/domainTypes.js";
+export type { ManagedDomainExports, DomainDeployPhase } from "../../../utils/domainTypes.js";
 export { getDomainExportNames } from "../../../utils/domainTypes.js";
 /**
  * Typed marker for the target of an `AliasRecord`. The helpers in
@@ -39,16 +40,10 @@ export type Certificate = string | {
     readonly subjectAlternativeNames?: string[];
     readonly transparencyLogging?: boolean;
 };
-export interface SubdomainDelegation {
-    readonly subdomain: string;
-    readonly toAccount: string;
-    readonly auto?: boolean;
-}
 export interface DomainCommonProps {
     readonly zoneName: string;
     readonly records?: DnsRecord[];
     readonly certificates?: Certificate[];
-    readonly delegations?: SubdomainDelegation[];
     readonly tags?: Record<string, string>;
     readonly description?: string;
     readonly costAllocationEnvironment?: string;
@@ -60,8 +55,27 @@ export interface Route53ApexProps extends DomainCommonProps {
 export interface ExternalDelegatedProps extends DomainCommonProps {
     readonly registrar: "external-delegated";
     readonly delegatedSubdomain: string;
+    /**
+     * D8 — child-writes delegation. LITERAL ARN of the parent zone's
+     * DelegationRole (VD2-a: never `Fn.importValue`, which resolves
+     * same-account only). When present, the child zone UPSERTs its NS records
+     * into the parent zone via `CrossAccountZoneDelegationRecord`. The CLI
+     * injects this from `ManagedDomainBinding.delegationRoleArn` at deploy
+     * time; omit it for an externally-owned parent and add the NS records at
+     * the registrar instead (a synth warning reminds you the zone will not
+     * resolve until delegated).
+     */
+    readonly parentDelegationRoleArn?: string;
+    /**
+     * Two-step deploy gate (R2 cert-hang guard, generalised from
+     * `DevSubstrate.phase`). `"zone"` synthesises the child zone, delegation
+     * record and user records only; `"full"` (default) additionally issues the
+     * certificates — deploy that only after the delegated NS has propagated,
+     * else ACM DNS-validation hangs until CloudFormation rolls back.
+     */
+    readonly phase?: DomainDeployPhase;
 }
-export interface ExternalRecordsProps extends Omit<DomainCommonProps, "delegations"> {
+export interface ExternalRecordsProps extends DomainCommonProps {
     readonly registrar: "external-records";
 }
 export type DomainProps = Route53ApexProps | ExternalDelegatedProps | ExternalRecordsProps;

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

@@ -14,4 +14,3 @@ export { type ConnectorType, type ConnectionAccess, type MessagingAccess, type C
 export { type PatternType, type IPattern, type IPayload, type IPayloadProps, type IPatternProps, type AnyPattern, type PayloadDatabaseConfig, type PayloadComputeConfig, type PayloadCdnConfig, isPayloadPattern, isPattern } from "./pattern.js";
 export { type OrganisationType, type IOrganisation, type IPlatform, type IAccount, type AnyOrganisation, isOrganisation, isPlatform, isAccount, isOrganisationResource } from "./organisation.js";
 export { type IVpcPeer } from "./vpcPeer.js";
-export { type DnsRecordInput, type DelegationInput, type CertificateInput, type DomainApexProps, type DomainDelegatedProps, type IDomainProps } from "./domain.js";

package/dist/lib/patterns/aws/interfaces/index.js

@@ -22,3 +22,6 @@ export { CONNECTION_TYPE, isConnector, isConnectable, isConnectionConfig, isConn
 export { isPayloadPattern, isPattern } from "./pattern.js";
 // Organisation interfaces
 export { isOrganisation, isPlatform, isAccount, isOrganisationResource } from "./organisation.js";
+// Domain interfaces — the legacy `IDomainProps` family was deleted with the
+// H13 BIND-era layer; consumers use the `DomainProps` union exported from
+// the patterns barrel.

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

@@ -23,7 +23,7 @@ import { type Storage } from "../storage.js";
 import { type QueueMessaging } from "../messaging.js";
 import { type Cdn, type SmartCdnBehaviour, type StaticSiteRouting } from "../cdn.js";
 import { type LambdaFunction } from "../../../resources/aws/compute/index.js";
-import type { ManagedDomainExports } from "../../../utils/domainTypes.js";
+import type { ManagedDomainBinding, ManagedDomainExports } from "../../../utils/domainTypes.js";
 import type { PatternType } from "@fjall/util";
 export type { ProxyConfig, ReadReplicaConfig, CredentialsConfig, EncryptionConfig, AuroraEncryptionConfig, AuroraWriterConfig, AuroraReadersConfig, DatabaseInsightsConfig };
 /**
@@ -287,11 +287,13 @@ export interface PayloadCdnConfig {
  * }));
  *
  * @example
- * // With custom domain (auto-creates certificate + DNS)
+ * // With custom domain (auto-creates certificate + DNS; the zone identity
+ * // is explicit — a CLI-injected managedDomain binding, or zoneName)
  * app.addPattern(PatternFactory.build("PayloadApp", {
  *   type: "payload",
  *   name: "my-cms",
- *   domain: "cms.example.com"
+ *   domain: "cms.example.com",
+ *   zoneName: "example.com"
  * }));
  *
  * @example
@@ -316,18 +318,42 @@ export interface IPayloadProps {
     /**
      * Custom domain for the Payload application.
      * When provided, automatically:
-     * - Looks up the Route53 hosted zone
-     * - Creates an ACM certificate with DNS validation (in us-east-1)
+     * - Resolves the Route53 hosted zone from the explicit identity
+     *   (`managedDomain` or `zoneName`/`hostedZoneId`) — never guessed from
+     *   the domain's labels
+     * - Provides a us-east-1 ACM certificate for CloudFront: the managed
+     *   binding's literal ARN, or an app-owned DNS-validated certificate
+     *   (in-stack for us-east-1 apps, otherwise in the app's dedicated
+     *   us-east-1 certificate stack consumed via cross-region references)
      * - Configures CloudFront with the certificate
      * - Creates an A record (alias) pointing to CloudFront
      *
-     * Requires: A Route53 hosted zone for the domain must exist.
+     * Requires: `managedDomain` or `zoneName` naming the zone that contains
+     * the domain.
      *
      * @example "cms.example.com"
      */
     domain?: string;
-    /** Import zone and cert from a managed domain stack instead of creating inline */
-    managedDomain?: ManagedDomainExports;
+    /**
+     * Zone and certificate identity from a managed domain stack. The
+     * CLI-injected `ManagedDomainBinding` carries literal values (hosted-zone
+     * ID + us-east-1 certificate ARN) and crosses accounts and regions; the
+     * legacy `ManagedDomainExports` form imports by export name (same account
+     * and region only). Takes priority over `zoneName`.
+     */
+    managedDomain?: ManagedDomainExports | ManagedDomainBinding;
+    /**
+     * Explicit hosted-zone name containing `domain` (BYO zones). Fjall never
+     * derives the zone from the domain's labels — set this when not using a
+     * managed domain. `domain` must sit within this zone (validated at synth).
+     * @example "example.com.au"
+     */
+    zoneName?: string;
+    /**
+     * Literal hosted-zone ID for `zoneName`. Optional — when set, the zone is
+     * referenced directly instead of via a runtime `HostedZone.fromLookup`.
+     */
+    hostedZoneId?: string;
     /** Database configuration */
     database?: PayloadDatabaseConfig;
     /** Compute (Lambda) configuration */
@@ -413,6 +439,7 @@ export interface StaticSiteCdnConfig {
  *   routing: "multipage",
  *   security: { headers: true },
  *   domain: "lbexc.com",
+ *   zoneName: "lbexc.com", // or a CLI-injected `managedDomain` binding
  *   forms: { to: "hello@lbexc.com", corsOrigin: "https://lbexc.com" }
  * }));
  */
@@ -431,8 +458,26 @@ export interface IStaticSiteProps {
     security?: StaticSiteSecurityConfig;
     /** Custom domain (same machinery as payload). Required when `forms` is set. */
     domain?: string;
-    /** Import zone and cert from a managed domain stack instead of creating inline */
-    managedDomain?: ManagedDomainExports;
+    /**
+     * Zone and certificate identity from a managed domain stack. The
+     * CLI-injected `ManagedDomainBinding` carries literal values (hosted-zone
+     * ID + us-east-1 certificate ARN) and crosses accounts and regions; the
+     * legacy `ManagedDomainExports` form imports by export name (same account
+     * and region only). Takes priority over `zoneName`.
+     */
+    managedDomain?: ManagedDomainExports | ManagedDomainBinding;
+    /**
+     * Explicit hosted-zone name containing `domain` (BYO zones). Fjall never
+     * derives the zone from the domain's labels — set this when not using a
+     * managed domain. `domain` must sit within this zone (validated at synth).
+     * @example "example.com.au"
+     */
+    zoneName?: string;
+    /**
+     * Literal hosted-zone ID for `zoneName`. Optional — when set, the zone is
+     * referenced directly instead of via a runtime `HostedZone.fromLookup`.
+     */
+    hostedZoneId?: string;
     /** Optional contact-form endpoint (Lambda → SES). Requires `domain`. */
     forms?: StaticSiteFormsConfig;
     /** CDN configuration - for advanced per-path overrides. */