@fjall/components-infrastructure 3.10.0 → 4.0.0

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

@@ -24,6 +24,10 @@ export function composeApexDomain(scope, props) {
     const hostedZoneConstruct = new HostedZone(scope, `${safeZone}HostedZone`, {
         zoneName: props.zoneName,
         hostedZoneId: props.hostedZoneId,
+        // Apex pins the legacy first-label naming: fjallDelegateHostedZoneRole
+        // is LIVE in production and children hold its LITERAL ARN - the default
+        // full-zone naming would REPLACE the role and sever every child.
+        delegationRoleNaming: "first-label",
         costAllocationEnvironment: props.costAllocationEnvironment,
         costAllocationDomain: props.zoneName
     });

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

@@ -8,7 +8,7 @@ import { applyInferredPublicBuildArgs } from "./computeBuildArgInference.js";
 import { DEFAULT_ECS_FALLBACK_IMAGE, DEFAULT_EC2_INSTANCE_TYPE } from "../../resources/aws/compute/ecsConstants.js";
 // Import and re-export from per-pattern files
 import { EcsCompute, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, validateEcsProps, buildContainerConfigs, expandMigrationsSugar, resolveScalingConfig } from "./computeEcs.js";
-import { LambdaCompute, resolveLambdaDeployment, lambdaImageKey, Architecture, HttpMethod, InvokeMode } from "./computeLambda.js";
+import { LambdaCompute, resolveLambdaDeployment, lambdaImageKey, toManifestLambdaArchitecture, Architecture, HttpMethod, InvokeMode } from "./computeLambda.js";
 import { Ec2Compute } from "./computeEc2.js";
 // Re-export everything from per-pattern files
 export { 
@@ -259,6 +259,14 @@ export class ComputeFactory {
                         lambdaComputeProps.docker !== undefined) {
                         manifestLambda.docker = lambdaComputeProps.docker;
                         manifestLambda.imageKey = lambdaImageKey(lambdaComputeProps, id);
+                        // Tells `fjall deploy` which platform to build so the pushed
+                        // image's architecture matches this function's `Architectures` —
+                        // without it the build pipeline always defaults to arm64.
+                        const architecture = toManifestLambdaArchitecture(lambdaComputeProps.architecture ??
+                            COMPUTE_DEFAULTS.LAMBDA.ARCHITECTURE);
+                        if (architecture !== undefined) {
+                            manifestLambda.architecture = architecture;
+                        }
                     }
                     collector.addLambda(manifestLambda);
                     return new LambdaCompute(scope, id, lambdaComputeProps);

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

@@ -8,7 +8,7 @@ import { type ILambdaCompute } from "./interfaces/compute.js";
 import { type ConnectionSpec } from "./interfaces/connector.js";
 import { LambdaFunction } from "../../resources/aws/compute/lambda.js";
 import { type SecretImport } from "../../resources/aws/secrets/index.js";
-import { type DockerBuild } from "@fjall/util/manifest/schemas";
+import { type DockerBuild, type LambdaArchitecture } from "@fjall/util/manifest/schemas";
 export { Architecture, HttpMethod, InvokeMode, type FunctionUrlCorsOptions } from "aws-cdk-lib/aws-lambda";
 /**
  * Lambda function URL configuration.
@@ -36,7 +36,13 @@ interface BaseLambdaProps {
     /** Memory size in MB. Default: 128 */
     memorySize?: number;
     ephemeralStorageSize?: number;
-    /** CPU architecture. Default: x86_64. Use Architecture.ARM_64 for Graviton2. */
+    /**
+     * CPU architecture. Default: Architecture.ARM_64 (Graviton2). Use
+     * Architecture.X86_64 for x86. For `deployment: "container"` with `docker`
+     * set, this also controls which platform `fjall deploy` builds the image
+     * for — the two must always agree, so set this instead of passing
+     * `--platform` to Docker directly.
+     */
     architecture?: Architecture;
     /** Lambda function description */
     description?: string;
@@ -156,6 +162,23 @@ export interface ContainerLambdaProps extends BaseLambdaProps {
      * `docker` is set.
      */
     image?: string;
+    /**
+     * Override the container's ENTRYPOINT (exec form, e.g.
+     * `["/lambda-entrypoint.sh"]`). Maps to Lambda's `ImageConfig.EntryPoint`.
+     * Default: use the image's own ENTRYPOINT.
+     */
+    entrypoint?: string[];
+    /**
+     * Override the container's CMD — i.e. the "docker run command" Lambda
+     * invokes as the handler (exec form, e.g. `["app.handler"]`). Maps to
+     * Lambda's `ImageConfig.Command`. Default: use the image's own CMD.
+     */
+    cmd?: string[];
+    /**
+     * Override the container's WORKDIR. Maps to Lambda's
+     * `ImageConfig.WorkingDirectory`. Default: use the image's own WORKDIR.
+     */
+    workingDirectory?: string;
 }
 /**
  * Code-based Lambda using inline code or S3.
@@ -219,6 +242,17 @@ export interface ResolvedLambdaDeployment {
 export declare function lambdaImageKey(props: {
     image?: string;
 }, id: string): string;
+/**
+ * Project a CDK `Architecture` onto the manifest's `LambdaArchitecture`
+ * literal, so `fjall deploy` builds the same platform the function is
+ * configured to run on instead of always defaulting to arm64
+ * (`dockerPlatformForArchitecture`, `@fjall/util/docker`).
+ *
+ * Returns `undefined` for a custom architecture name (`Architecture.custom`)
+ * outside the two AWS Lambda supports today — the build pipeline then falls
+ * back to its own default rather than failing synth over an escape hatch.
+ */
+export declare function toManifestLambdaArchitecture(architecture: Architecture): LambdaArchitecture | undefined;
 /**
  * Resolve Lambda deployment configuration from props.
  * Handles container vs code deployment types.

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

@@ -6,6 +6,7 @@ import { processConnections } from "../../utils/connections.js";
 import { LambdaFunction } from "../../resources/aws/compute/lambda.js";
 import { getOrCreateImageTagParameter } from "../../resources/aws/compute/imageTagParameter.js";
 import { COMPUTE_DEFAULTS } from "./compute.js";
+import { LAMBDA_ARCHITECTURE_VALUES } from "@fjall/util/manifest/schemas";
 import { evaluateBakeGuard } from "@fjall/util/docker";
 import { toKebab } from "@fjall/util";
 // Re-export Lambda types from CDK for user convenience
@@ -22,6 +23,50 @@ export { Architecture, HttpMethod, InvokeMode } from "aws-cdk-lib/aws-lambda";
 export function lambdaImageKey(props, id) {
     return props.image !== undefined && props.image !== "" ? props.image : id;
 }
+/**
+ * Project a CDK `Architecture` onto the manifest's `LambdaArchitecture`
+ * literal, so `fjall deploy` builds the same platform the function is
+ * configured to run on instead of always defaulting to arm64
+ * (`dockerPlatformForArchitecture`, `@fjall/util/docker`).
+ *
+ * Returns `undefined` for a custom architecture name (`Architecture.custom`)
+ * outside the two AWS Lambda supports today — the build pipeline then falls
+ * back to its own default rather than failing synth over an escape hatch.
+ */
+export function toManifestLambdaArchitecture(architecture) {
+    return LAMBDA_ARCHITECTURE_VALUES.includes(architecture.name)
+        ? architecture.name
+        : undefined;
+}
+/**
+ * Project `ContainerLambdaProps`'s ENTRYPOINT/CMD/WORKDIR overrides onto the
+ * `EcrImageCodeProps` shape `Code.fromEcrImage` expects, omitting any field
+ * left unset so the image's own Dockerfile values apply (CDK's own default
+ * behaviour when these keys are absent).
+ *
+ * Degenerate values fail synth: an empty array or blank string is neither a
+ * usable override nor "use the image default", so passing it through would
+ * surface as a deploy/invoke-time ImageConfig failure instead of here.
+ */
+function imageOverrides(props, id) {
+    if (props.entrypoint !== undefined && props.entrypoint.length === 0) {
+        throw new Error(`Lambda '${id}': \`entrypoint\` override must not be an empty array — omit the prop to keep the image's ENTRYPOINT.`);
+    }
+    if (props.cmd !== undefined && props.cmd.length === 0) {
+        throw new Error(`Lambda '${id}': \`cmd\` override must not be an empty array — omit the prop to keep the image's CMD.`);
+    }
+    if (props.workingDirectory !== undefined &&
+        props.workingDirectory.trim() === "") {
+        throw new Error(`Lambda '${id}': \`workingDirectory\` override must not be blank — omit the prop to keep the image's WORKDIR.`);
+    }
+    return {
+        ...(props.entrypoint !== undefined && { entrypoint: props.entrypoint }),
+        ...(props.cmd !== undefined && { cmd: props.cmd }),
+        ...(props.workingDirectory !== undefined && {
+            workingDirectory: props.workingDirectory
+        })
+    };
+}
 /**
  * Resolve Lambda deployment configuration from props.
  * Handles container vs code deployment types.
@@ -53,7 +98,8 @@ export function resolveLambdaDeployment(scope, id, props) {
             });
             return {
                 code: Code.fromEcrImage(props.ecrRepository, {
-                    tagOrDigest: param.valueAsString
+                    tagOrDigest: param.valueAsString,
+                    ...imageOverrides(props, id)
                 }),
                 handler: Handler.FROM_IMAGE,
                 runtime: Runtime.FROM_IMAGE
@@ -61,7 +107,8 @@ export function resolveLambdaDeployment(scope, id, props) {
         }
         return {
             code: Code.fromEcrImage(props.ecrRepository, {
-                tagOrDigest: COMPUTE_DEFAULTS.ECS.IMAGE_TAG
+                tagOrDigest: COMPUTE_DEFAULTS.ECS.IMAGE_TAG,
+                ...imageOverrides(props, id)
             }),
             handler: Handler.FROM_IMAGE,
             runtime: Runtime.FROM_IMAGE

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

@@ -34,6 +34,9 @@ const COMPUTE_PROP_APPLICABILITY = {
     ssmSecretsPath: ["lambda"],
     secretsImport: ["lambda"],
     connections: ["lambda"],
+    entrypoint: ["lambda"],
+    cmd: ["lambda"],
+    workingDirectory: ["lambda"],
     instanceType: ["ec2"],
     ssh: ["ec2"],
     userData: ["ec2"],
@@ -76,6 +79,9 @@ const LAMBDA_DEPLOYMENT_APPLICABILITY = {
     ecrRepository: "container",
     docker: "container",
     image: "container",
+    entrypoint: "container",
+    cmd: "container",
+    workingDirectory: "container",
     code: "code",
     handler: "code",
     runtime: "code"

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

@@ -28,13 +28,18 @@ import { DOMAIN_DEPLOY_DEFAULT_PHASE } from "../../utils/domainTypes.js";
 export function composeDelegatedDomain(scope, props) {
     const effectiveZone = `${props.delegatedSubdomain}.${props.zoneName}`;
     const safeZone = toPascalCase(getSafeZoneName(effectiveZone));
+    // `createDelegationRole` is deliberately omitted (mirroring the apex
+    // pattern): the wrapper's org-gated default mints the DelegationRole + ARN
+    // export for created AND adopted delegated zones, making this zone a
+    // delegating PARENT that nested children (k8.development.fjall.io-class)
+    // can assume. Default full-zone role naming applies - delegated children
+    // reuse first labels (dev/staging/k8), so first-label names would collide
+    // account-globally.
     const hostedZoneConstruct = new HostedZone(scope, `${safeZone}HostedZone`, {
         zoneName: effectiveZone,
         // Adoption path: an existing child zone is imported by id rather than
         // created (both-or-neither with adoptedNameServers, validated upstream).
         hostedZoneId: props.hostedZoneId,
-        // The PARENT account owns the delegation role — this is the child.
-        createDelegationRole: false,
         costAllocationEnvironment: props.costAllocationEnvironment,
         costAllocationDomain: props.zoneName
     });

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

@@ -1,13 +1,14 @@
 import { CfnOutput, Duration, Stack, Tags } from "aws-cdk-lib";
 import { Port } from "aws-cdk-lib/aws-ec2";
 import { Cluster } from "aws-cdk-lib/aws-ecs";
-import { Repository, TagMutability } from "aws-cdk-lib/aws-ecr";
+import { Repository, TagMutability, TagStatus } from "aws-cdk-lib/aws-ecr";
 import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
 import { Code, Runtime } from "aws-cdk-lib/aws-lambda";
 import { PublicHostedZone } from "aws-cdk-lib/aws-route53";
 import { LoadBalancerTarget } from "aws-cdk-lib/aws-route53-targets";
 import { SqsDestination } from "aws-cdk-lib/aws-s3-notifications";
 import { Construct } from "constructs";
+import { buildCacheRepositoryName, CACHE_REPO_UNTAGGED_RETENTION_DAYS } from "@fjall/util/docker";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -249,6 +250,30 @@ export class DevSubstrate extends Construct {
                 // first same-branch recreate (BUG-22).
                 tagMutability: TagMutability.MUTABLE
             });
+        // Buildx registry cache for slot builds, named by the same helper as the app
+        // path's `<repo>-cache` so `fjall dev up` derives this URI from the slot
+        // repo's without a second wire field. Adopts on the same flag: both repos are
+        // RETAIN, so a rolled-back create leaves BOTH behind, and a create-only cache
+        // repo would fail the very retry `adoptSlotEcr` exists to rescue.
+        const slotCacheRepositoryName = buildCacheRepositoryName(slotEcrRepositoryName);
+        if (props.adoptSlotEcr === true) {
+            Repository.fromRepositoryName(this, `${slotEcrId}Cache`, slotCacheRepositoryName);
+        }
+        else {
+            const slotCacheRepository = new Ecr(this, `${slotEcrId}Cache`, {
+                repositoryName: slotCacheRepositoryName,
+                // buildx overwrites the per-repo cache manifest tag on every export.
+                tagMutability: TagMutability.MUTABLE
+            });
+            // Each `mode=max` export orphans the previous manifest's blobs. The
+            // dev-deploy role holds no BatchDeleteImage or PutLifecyclePolicy, so this
+            // rule is the ONLY reclaim path — without it the cache grows without bound
+            // in a customer's dev account. An adopted repo keeps its existing policy.
+            slotCacheRepository.addLifecycleRule({
+                tagStatus: TagStatus.UNTAGGED,
+                maxImageAge: Duration.days(CACHE_REPO_UNTAGGED_RETENTION_DAYS)
+            });
+        }
         return {
             vpc,
             slotSecurityGroup,

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

@@ -29,5 +29,5 @@ export declare class Domain extends Construct {
     readonly nameServers: string[] | undefined;
     readonly manualRecords: ManualRecord[];
     readonly exportNames: ReturnType<typeof getDomainExportNames>;
-    constructor(scope: Construct, id: string, props: DomainProps);
+    constructor(scope: Construct, id: string, rawProps: DomainProps);
 }

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

@@ -32,8 +32,17 @@ export class Domain extends Construct {
     nameServers;
     manualRecords;
     exportNames;
-    constructor(scope, id, props) {
+    constructor(scope, id, rawProps) {
         super(scope, id);
+        // N6b hand-edit-trap guard: the CLI injects the deploy phase and parent
+        // role ARN as CDK context, historically read only by the
+        // tsEmitter-generated infrastructure.ts prelude - a hand-edited file
+        // without it silently lost phase-gating (R2 cert-hang) and the injected
+        // ARN. Merged BEFORE validation so context-sourced values face the same
+        // checks as props.
+        const props = rawProps.registrar === "external-delegated"
+            ? applyDelegatedContextFallback(this, rawProps)
+            : rawProps;
         validateDomainProps(this, props);
         this.registrar = props.registrar;
         this.exportNames = getDomainExportNames(resolveEffectiveZoneName(props));
@@ -115,3 +124,50 @@ function resolveEffectiveZoneName(props) {
     }
     return props.zoneName;
 }
+// CLI injection channel for the delegated-child topology - keep the key
+// literals in sync with deploy-core CdkArgumentBuilder.buildContextArgs and
+// the cli tsEmitter prelude.
+const CONTEXT_KEY_DOMAIN_DEPLOY_PHASE = "fjall:domainDeployPhase";
+const CONTEXT_KEY_PARENT_DELEGATION_ROLE_ARN = "fjall:parentDelegationRoleArn";
+/**
+ * Context FALLBACK only - explicit props always win, so a
+ * tsEmitter-generated file that already read the context and passed props
+ * cannot double-apply a diverging value. `undefined` and the `-c key=`
+ * empty-string boundary both mean "not injected". An unrecognised phase
+ * fails the synth: silently ignoring it would issue certificates during the
+ * zone phase (the R2 trap). Non-delegated registrars never reach this -
+ * they must ignore the injected keys rather than trip the
+ * delegated-props-only validation.
+ */
+function applyDelegatedContextFallback(scope, props) {
+    let merged = props;
+    if (merged.phase === undefined) {
+        const rawPhase = scope.node.tryGetContext(CONTEXT_KEY_DOMAIN_DEPLOY_PHASE);
+        if (rawPhase !== undefined && rawPhase !== "") {
+            if (rawPhase !== "zone" && rawPhase !== "full") {
+                throw new Error(`Domain '${props.delegatedSubdomain}.${props.zoneName}': CDK ` +
+                    `context '${CONTEXT_KEY_DOMAIN_DEPLOY_PHASE}' must be "zone" or ` +
+                    `"full" (got ${JSON.stringify(rawPhase)}). Cure: re-run the ` +
+                    `deploy through the Fjall CLI, or correct the hand-set context ` +
+                    `entry.`);
+            }
+            merged = { ...merged, phase: rawPhase };
+        }
+    }
+    if (merged.parentDelegationRoleArn === undefined) {
+        const rawArn = scope.node.tryGetContext(CONTEXT_KEY_PARENT_DELEGATION_ROLE_ARN);
+        if (rawArn !== undefined && rawArn !== "") {
+            if (typeof rawArn !== "string") {
+                throw new Error(`Domain '${props.delegatedSubdomain}.${props.zoneName}': CDK ` +
+                    `context '${CONTEXT_KEY_PARENT_DELEGATION_ROLE_ARN}' must be a ` +
+                    `string IAM role ARN (got ${JSON.stringify(rawArn)}). Cure: ` +
+                    `re-run the deploy through the Fjall CLI, or correct the ` +
+                    `hand-set context entry.`);
+            }
+            // ARN-shape/token checks run in validateDomainProps on the merged
+            // props - a malformed injected value must fail the synth there.
+            merged = { ...merged, parentDelegationRoleArn: rawArn };
+        }
+    }
+    return merged;
+}

package/dist/lib/resources/aws/iam/delegationRole.d.ts

@@ -1,10 +1,37 @@
 import { Construct } from "constructs";
 import { type IRole } from "aws-cdk-lib/aws-iam";
 import type { IHostedZone } from "aws-cdk-lib/aws-route53";
+/**
+ * Physical-role-name derivation strategy.
+ *
+ * - `"full-zone"` (default): the name derives from every zone label, so two
+ *   role-minting zones sharing a first label in one account (delegated
+ *   children reuse labels like dev/staging/k8) get distinct names. Residual
+ *   collision class: IAM compares RoleNames case-insensitively and the
+ *   pascal-casing erases dot positions, so zones whose concatenated labels
+ *   are equal ignoring case (staging.api.example.com vs
+ *   stagingapi.example.com) still map to IAM-equal names - the failure is
+ *   loud (CloudFormation EntityAlreadyExists rollback), never silent.
+ * - `"first-label"`: the legacy contract, and the DEFAULT before this prop
+ *   existed. `fjallDelegateHostedZoneRole` is LIVE in production and
+ *   children hold its LITERAL ARN - renaming replaces the role and severs
+ *   them, so apex zones pin this explicitly. Any direct consumer of this
+ *   construct (or HostedZone) with a role deployed under the old default
+ *   must pin `"first-label"` on upgrade: the default flip changes BOTH the
+ *   RoleName and the construct id, i.e. role REPLACEMENT.
+ */
+export type DelegationRoleNaming = "full-zone" | "first-label";
 export interface DelegationRoleProps {
     readonly zoneName: string;
     readonly hostedZone: IHostedZone;
-    readonly organisationIdExportName?: string;
+    /**
+     * LITERAL AWS Organization id for the trust policy (aws:PrincipalOrgID).
+     * Resolved at synth from CDK context by the HostedZone wrapper - never a
+     * CFN import: the role mints in child accounts that may carry no
+     * OrganisationId export, where an Fn::ImportValue rolls the stack back.
+     */
+    readonly organisationId: string;
+    readonly naming?: DelegationRoleNaming;
     readonly description?: string;
     readonly costAllocationEnvironment?: string;
     readonly costAllocationDomain?: string;

package/dist/lib/resources/aws/iam/delegationRole.js

@@ -1,10 +1,38 @@
+import { createHash } from "node:crypto";
 import { Construct } from "constructs";
-import { ArnFormat, CfnOutput, Fn, Stack, Tags } from "aws-cdk-lib";
+import { ArnFormat, CfnOutput, Stack, Tags } from "aws-cdk-lib";
 import { OrganizationPrincipal, PolicyDocument, PolicyStatement } from "aws-cdk-lib/aws-iam";
 import { getDomainExportNames } from "@fjall/util";
 import { Role } from "./role.js";
-import { toPascalCase, getSafeZoneName } from "../../../utils/capitaliseString.js";
+import { capitaliseString, toPascalCase, getSafeZoneName } from "../../../utils/capitaliseString.js";
 import { DEFAULT_COST_ALLOCATION_ENVIRONMENT } from "../../../utils/costAllocationTags.js";
+// The suffix is a deployed contract: the SCP dev-isolation carve-out
+// wildcards arn:aws:iam::*:role/*DelegateHostedZoneRole (scpPreset).
+const ROLE_NAME_SUFFIX = "DelegateHostedZoneRole";
+// IAM caps RoleName at 64 chars; 40 + the 22-char suffix leaves headroom.
+const MAX_ZONE_PART_LENGTH = 40;
+// Truncated stem + hash must land exactly on MAX_ZONE_PART_LENGTH.
+const TRUNCATED_STEM_LENGTH = 32;
+const ZONE_HASH_LENGTH = 8;
+/**
+ * Full-zone role-name stem: first label verbatim, every later label
+ * capitalised (k8.development.fjall.io -> k8DevelopmentFjallIo). Over-long
+ * stems truncate to a fixed-length prefix plus a stable sha256 fragment of
+ * the whole zone name, keeping the name deterministic per zone and distinct
+ * across zones that share a long prefix.
+ */
+function deriveFullZoneStem(zoneName) {
+    const labels = zoneName.split(".");
+    const stem = labels[0] + labels.slice(1).map(capitaliseString).join("");
+    if (stem.length <= MAX_ZONE_PART_LENGTH) {
+        return stem;
+    }
+    const hash = createHash("sha256")
+        .update(zoneName)
+        .digest("hex")
+        .slice(0, ZONE_HASH_LENGTH);
+    return stem.slice(0, TRUNCATED_STEM_LENGTH) + hash;
+}
 export class DelegationRole extends Construct {
     role;
     roleArn;
@@ -13,14 +41,19 @@ export class DelegationRole extends Construct {
     constructor(scope, id, props) {
         super(scope, id);
         const firstLabel = props.zoneName.split(".")[0];
-        const safeFirstLabel = toPascalCase(firstLabel);
         const safeZone = toPascalCase(getSafeZoneName(props.zoneName));
+        const stem = (props.naming ?? "full-zone") === "first-label"
+            ? firstLabel
+            : deriveFullZoneStem(props.zoneName);
+        // First-label construct id must stay byte-identical to the deployed apex
+        // logical IDs (an id change is a role REPLACEMENT on live stacks).
+        const constructId = `${toPascalCase(stem)}${ROLE_NAME_SUFFIX}`;
         this.description =
             props.description ??
                 `Fjall-managed cross-account delegation role for ${props.zoneName}`;
-        const role = new Role(this, `${safeFirstLabel}DelegateHostedZoneRole`, {
-            assumedBy: new OrganizationPrincipal(Fn.importValue(props.organisationIdExportName ?? "OrganisationId")),
-            roleName: `${firstLabel}DelegateHostedZoneRole`,
+        const role = new Role(this, constructId, {
+            assumedBy: new OrganizationPrincipal(props.organisationId),
+            roleName: `${stem}${ROLE_NAME_SUFFIX}`,
             description: this.description,
             inlinePolicies: {
                 listHostedZones: new PolicyDocument({

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

@@ -1,14 +1,25 @@
 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 { DelegationRole, type DelegationRoleNaming } from "../iam/delegationRole.js";
 import { type AwsStack } from "../base/awsStack.js";
 export interface HostedZoneProps {
     readonly zoneName: string;
     readonly hostedZoneId?: string;
     readonly description?: string;
     readonly createDelegationRole?: boolean;
-    readonly organisationIdExportName?: string;
+    /**
+     * Physical naming for the minted DelegationRole. Default `"full-zone"`:
+     * delegated zones reuse first labels (dev/staging/k8) in one account, so
+     * first-label names would collide account-globally. Apex patterns pin
+     * `"first-label"` because that role name is a deployed contract (children
+     * hold its literal ARN). BREAKING default flip: before this prop existed
+     * every minted role was first-label-named - a consumer upgrading with a
+     * previously deployed default-named role must pin `"first-label"` or the
+     * rename (RoleName and construct id both change) REPLACES the role and
+     * severs children holding its literal ARN.
+     */
+    readonly delegationRoleNaming?: DelegationRoleNaming;
     readonly costAllocationEnvironment?: string;
     readonly costAllocationDomain?: string;
     /**

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

@@ -72,22 +72,27 @@ export class HostedZone extends Construct {
             this.isImported = true;
             Tags.of(this).add("fjall:description", this.description);
         }
-        // Org-gate: a single account has no OrganisationId export, so an org-trusting
-        // delegation role would leave an unresolved Fn::ImportValue and roll the stack
-        // back. Default follows org presence; explicit `true` opts in (and fails fast).
+        // Org-gate: an org-trusting delegation role is meaningless on a single
+        // account, so the default follows org presence; explicit `true` opts in
+        // (and fails fast). The synth-resolved orgId LITERAL feeds the trust
+        // policy directly - never a CFN import, which would tie every
+        // role-minting account to an Account governance stack export.
         // Runs for created AND adopted zones — `grantDelegation` is on IHostedZone.
-        const inOrganisation = resolveOrgId(this.node) !== undefined;
-        if (props.createDelegationRole === true && !inOrganisation) {
+        const orgId = resolveOrgId(this.node);
+        if (props.createDelegationRole === true && orgId === undefined) {
             throw new Error(`HostedZone "${props.zoneName}": createDelegationRole was requested but ` +
                 `this account is not part of an AWS Organization (no "orgId" context). ` +
                 `Cross-account DNS delegation requires an organisation — omit ` +
                 `createDelegationRole for single-account setups, or connect an organisation.`);
         }
-        if (props.createDelegationRole ?? inOrganisation) {
+        // Equivalent to `props.createDelegationRole ?? inOrganisation`: the
+        // explicit-true-without-org case already threw, so orgId is narrowed.
+        if (orgId !== undefined && (props.createDelegationRole ?? true)) {
             this.delegationRole = new DelegationRole(this, `${safeZone}DelegationRole`, {
                 zoneName: props.zoneName,
                 hostedZone: this.hostedZone,
-                organisationIdExportName: props.organisationIdExportName,
+                organisationId: orgId,
+                naming: props.delegationRoleNaming,
                 costAllocationEnvironment: props.costAllocationEnvironment,
                 costAllocationDomain: props.costAllocationDomain
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "3.10.0",
+  "version": "4.0.0",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
@@ -67,8 +67,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1038.0",
-    "@fjall/generator": "^3.10.0",
-    "@fjall/util": "^3.10.0",
+    "@fjall/generator": "^4.0.0",
+    "@fjall/util": "^4.0.0",
     "constructs": "^10.6.0"
   },
   "overrides": {
@@ -82,5 +82,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "gitHead": "ce4e8471194f7e3e5e7df66844bf9387503983f6"
+  "gitHead": "14031063ccd2685e390b70f6a3f4efe2bac7ced9"
 }