@fjall/components-infrastructure 3.1.0 → 3.3.0

package/dist/lib/app.d.ts

@@ -16,7 +16,7 @@ import { type RemovalPolicyString } from "./resources/aws/messaging/utils.js";
 import { type ServiceRegistrationProps } from "./resources/aws/networking/serviceDiscovery.js";
 import { type IPrivateDnsNamespace, type IService } from "aws-cdk-lib/aws-servicediscovery";
 import { type AnyCompute } from "./patterns/aws/compute.js";
-import { Buildkite, type BuildkitePropsInput } from "./patterns/aws/buildkite.js";
+import { type Buildkite, type BuildkiteFactoryFn, type BuildkitePropsInput } from "./patterns/aws/buildkite.js";
 import { DevSubstrate, type IDevSubstrateProps } from "./patterns/aws/devSubstrate.js";
 import { type Storage, type StorageFactoryFn } from "./patterns/aws/storage.js";
 import { type AnyPattern, type PatternFactoryFn } from "./patterns/aws/pattern.js";
@@ -288,12 +288,19 @@ export declare class App extends CdkApp {
      * same registry posture — Fjall-managed platform infrastructure,
      * deliberately NOT on the customer create/scaffold surface (design § D3).
      *
-     * Cost-allocation environment resolves from `getConfig()` (design § D10) so
-     * the fleet's environment tag matches the deploying config rather than the
-     * construct's `management` fallback; an explicit
-     * `props.costAllocationEnvironment` still wins.
+     * App-level defaults (cost-allocation environment from `getConfig()`,
+     * alarm actions to the account's `SharedAlarmTopicArn` export,
+     * `applicationId` to the app name — designs § D10/§ D14) are resolved by
+     * `resolveBuildkiteConstructProps`; explicit props always win.
+     *
+     * The props overload pins construct id `"Buildkite"` (byte-identical
+     * logical IDs for pre-factory consumers); the factory overload accepts
+     * `BuildkiteFactory.build(id, props)` — the shape the codemod add path
+     * emits. Both overloads resolve placement here, so the deploy-core
+     * fixed-stack contract cannot be bypassed from an emitted statement.
      */
     addBuildkite(props: BuildkitePropsInput): Buildkite;
+    addBuildkite(fn: BuildkiteFactoryFn): Buildkite;
     /**
      * Add a database resource to the default database stack using the factory pattern.
      * Returns the appropriate database type based on the factory used.

package/dist/lib/app.js

@@ -9,13 +9,12 @@ import { NetworkFactory } from "./patterns/aws/network.js";
 import { MessagingFactory } from "./patterns/aws/messaging.js";
 import { Schedule } from "./resources/aws/messaging/schedule.js";
 import { ServiceDiscoveryNamespace } from "./resources/aws/networking/serviceDiscovery.js";
-import { Buildkite } from "./patterns/aws/buildkite.js";
+import { BuildkiteFactory } from "./patterns/aws/buildkite.js";
 import { DevSubstrate } from "./patterns/aws/devSubstrate.js";
 import { StandardTagsAspect } from "./utils/standardTagsAspect.js";
 import { BACKUP_TIER_TAG_KEY, BACKUP_TIER_TAG_MAP } from "./utils/backupTierMapping.js";
 import { randomBytes } from "crypto";
 import { getConfig } from "./utils/getConfig.js";
-import { UNKNOWN_ENVIRONMENT } from "./utils/env.js";
 import AuditRoleFactory from "./resources/aws/audit/auditRole.js";
 import { FJALL_AUDIT_CONFIG } from "./config/audit.js";
 import { FjallLogger } from "./utils/validationLogger.js";
@@ -482,33 +481,12 @@ export class App extends CdkApp {
         computeStack.addConstruct(substrate);
         return substrate;
     }
-    /**
-     * Instantiate the self-hosted Buildkite agent fleet on the default compute
-     * stack (design `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`).
-     *
-     * Same placement contract as `addDevSubstrate` above: deploy-core selects
-     * stacks by the fixed six-category enum, so scoping under
-     * `${stackPrefix}Compute` is what makes the fleet actually deploy. Also the
-     * same registry posture — Fjall-managed platform infrastructure,
-     * deliberately NOT on the customer create/scaffold surface (design § D3).
-     *
-     * Cost-allocation environment resolves from `getConfig()` (design § D10) so
-     * the fleet's environment tag matches the deploying config rather than the
-     * construct's `management` fallback; an explicit
-     * `props.costAllocationEnvironment` still wins.
-     */
-    addBuildkite(props) {
+    addBuildkite(input) {
+        const fn = typeof input === "function"
+            ? input
+            : BuildkiteFactory.build("Buildkite", input);
         const computeStack = this.getDefaultComputeStack();
-        const configEnvironment = getConfig().environment;
-        const constructProps = { ...props, vpc: this.getVpc() };
-        // Post-spread injection so a caller-materialised `costAllocationEnvironment:
-        // undefined` counts as absent rather than clobbering the resolved value.
-        if (constructProps.costAllocationEnvironment === undefined &&
-            configEnvironment !== "" &&
-            configEnvironment !== UNKNOWN_ENVIRONMENT) {
-            constructProps.costAllocationEnvironment = configEnvironment;
-        }
-        const fleet = new Buildkite(computeStack.getStack(), "Buildkite", constructProps);
+        const fleet = fn(this, computeStack.getStack());
         computeStack.addConstruct(fleet);
         return fleet;
     }

package/dist/lib/config/aws/alarmTopic.d.ts

@@ -1,6 +1,13 @@
 import { CfnOutput } from "aws-cdk-lib";
 import type { ITopic } from "aws-cdk-lib/aws-sns";
 import { Construct } from "constructs";
+/**
+ * The well-known cross-stack export name for the account's shared alarm
+ * topic. Consumers build `"import:" + SHARED_ALARM_TOPIC_EXPORT_NAME`
+ * strings for `resolveAlertsTopic`; the CfnOutput below is the single
+ * producer.
+ */
+export declare const SHARED_ALARM_TOPIC_EXPORT_NAME = "SharedAlarmTopicArn";
 export declare class SharedAlarmTopic extends Construct {
     readonly topic: ITopic;
     readonly topicArn: CfnOutput;

package/dist/lib/config/aws/alarmTopic.js

@@ -1,6 +1,13 @@
 import { CfnOutput } from "aws-cdk-lib";
 import { Construct } from "constructs";
 import { SNSTopic } from "../../resources/aws/messaging/sns.js";
+/**
+ * The well-known cross-stack export name for the account's shared alarm
+ * topic. Consumers build `"import:" + SHARED_ALARM_TOPIC_EXPORT_NAME`
+ * strings for `resolveAlertsTopic`; the CfnOutput below is the single
+ * producer.
+ */
+export const SHARED_ALARM_TOPIC_EXPORT_NAME = "SharedAlarmTopicArn";
 export class SharedAlarmTopic extends Construct {
     topic;
     topicArn;
@@ -15,9 +22,9 @@ export class SharedAlarmTopic extends Construct {
         // thinking it duplicates the wrapper's AlarmNotificationsTopicArn —
         // the wrapper's auto-output has no exportName and cannot be imported.
         this.topicArn = new CfnOutput(this, "SharedAlarmTopicArn", {
-            key: "SharedAlarmTopicArn",
+            key: SHARED_ALARM_TOPIC_EXPORT_NAME,
             value: wrapped.getTopicArn(),
-            exportName: "SharedAlarmTopicArn"
+            exportName: SHARED_ALARM_TOPIC_EXPORT_NAME
         });
     }
 }

package/dist/lib/config/aws/scpPreset.js

@@ -307,7 +307,14 @@ function buildDevIsolationGuardrails() {
                 Sid: "DenyCrossAccountAssumeRole",
                 Effect: "Deny",
                 Action: ["sts:AssumeRole", "sts:AssumeRoot"],
-                Resource: "*",
+                // NotResource carves delegation roles (the DelegationRole construct's
+                // fixed `<label>DelegateHostedZoneRole` naming contract) out of the
+                // deny — a delegated child domain deployed into a dev account must
+                // assume the parent zone's delegation role cross-account to write its
+                // NS. Those roles are NS-write-scoped by construction
+                // (delegationRole.ts). AssumeRoot stays denied everywhere: root-user
+                // ARNs never match the role pattern.
+                NotResource: "arn:aws:iam::*:role/*DelegateHostedZoneRole",
                 Condition: {
                     StringNotEquals: {
                         // IAM policy variable, substituted per-request by AWS — the

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

@@ -14,12 +14,12 @@ export interface ApexDomainPatternResult {
  *
  * Delegation direction (D8): child writes NS. The apex zone's contribution
  * to delegation is the org-gated `DelegationRole` the `HostedZone` wrapper
- * creates on the create path — the delegated child `Domain` assumes that
- * role by LITERAL ARN (`parentDelegationRoleArn`) and UPSERTs its own NS
- * records into this zone via `CrossAccountZoneDelegationRecord`. The old
- * parent-writes `delegations[]` path (NS records from `Fn.importValue` of
- * child nameserver exports) was removed with the H13 legacy layer: it was
- * export-locked, child-first-deploy-ordered, and removal required a parent
- * redeploy.
+ * creates for created AND adopted zones — the delegated child `Domain`
+ * assumes that role by LITERAL ARN (`parentDelegationRoleArn`) and UPSERTs
+ * its own NS records into this zone via `CrossAccountZoneDelegationRecord`.
+ * The old parent-writes `delegations[]` path (NS records from
+ * `Fn.importValue` of child nameserver exports) was removed with the H13
+ * legacy layer: it was export-locked, child-first-deploy-ordered, and
+ * removal required a parent redeploy.
  */
 export declare function composeApexDomain(scope: Construct, props: Route53ApexProps): ApexDomainPatternResult;

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

@@ -2,32 +2,28 @@ import { HostedZone } from "../../resources/aws/networking/hostedZone.js";
 import { DomainCertificate } from "../../resources/aws/networking/domainCertificate.js";
 import { composeTypedDnsRecords } from "./dnsRecordComposer.js";
 import { toPascalCase, getSafeZoneName } from "../../utils/capitaliseString.js";
-import { resolveOrgId } from "../../utils/cdkContext.js";
 /**
  * Composition for `registrar: "route53"`. Creates (or imports) the apex
  * `HostedZone` and composes all user records + certificates.
  *
  * Delegation direction (D8): child writes NS. The apex zone's contribution
  * to delegation is the org-gated `DelegationRole` the `HostedZone` wrapper
- * creates on the create path — the delegated child `Domain` assumes that
- * role by LITERAL ARN (`parentDelegationRoleArn`) and UPSERTs its own NS
- * records into this zone via `CrossAccountZoneDelegationRecord`. The old
- * parent-writes `delegations[]` path (NS records from `Fn.importValue` of
- * child nameserver exports) was removed with the H13 legacy layer: it was
- * export-locked, child-first-deploy-ordered, and removal required a parent
- * redeploy.
+ * creates for created AND adopted zones — the delegated child `Domain`
+ * assumes that role by LITERAL ARN (`parentDelegationRoleArn`) and UPSERTs
+ * its own NS records into this zone via `CrossAccountZoneDelegationRecord`.
+ * The old parent-writes `delegations[]` path (NS records from
+ * `Fn.importValue` of child nameserver exports) was removed with the H13
+ * legacy layer: it was export-locked, child-first-deploy-ordered, and
+ * removal required a parent redeploy.
  */
 export function composeApexDomain(scope, props) {
     const safeZone = toPascalCase(getSafeZoneName(props.zoneName));
-    // Gotcha: the cross-account DelegationRole imports CFN export `OrganisationId`
-    // from the org/account stack — only published when an `orgId` CDK context
-    // value is set. Single-account deploys would roll back at synth without
-    // this gate.
-    const inOrganisation = resolveOrgId(scope.node) !== undefined;
+    // Gotcha: `createDelegationRole` is deliberately omitted — the wrapper's
+    // org-gated default gives created AND adopted apex zones the DelegationRole;
+    // re-adding a create-path-only condition would strand adopted apexes (D8).
     const hostedZoneConstruct = new HostedZone(scope, `${safeZone}HostedZone`, {
         zoneName: props.zoneName,
         hostedZoneId: props.hostedZoneId,
-        createDelegationRole: props.hostedZoneId === undefined && inOrganisation,
         costAllocationEnvironment: props.costAllocationEnvironment,
         costAllocationDomain: props.zoneName
     });

package/dist/lib/patterns/aws/buildkite/alarms.d.ts

@@ -3,6 +3,11 @@ export interface BuildkiteAlarmParams {
     readonly buildkiteOrgSlug: string;
     readonly buildkiteQueue: string;
     readonly autoScalingGroupName: string;
+    /**
+     * Alarm-action destination, in either `resolveAlertsTopic` string shape:
+     * a literal `arn:...` or `"import:<ExportName>"` (e.g.
+     * `"import:SharedAlarmTopicArn"`). Omitted → alarms exist but page nobody.
+     */
     readonly alarmSnsTopicArn?: string;
 }
 /**

package/dist/lib/patterns/aws/buildkite/alarms.js

@@ -1,7 +1,7 @@
 import { Duration } from "aws-cdk-lib";
 import { Alarm, ComparisonOperator, MathExpression, Metric, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
 import { SnsAction } from "aws-cdk-lib/aws-cloudwatch-actions";
-import { Topic } from "aws-cdk-lib/aws-sns";
+import { resolveAlertsTopic } from "../../../utils/resolveAlertsTopic.js";
 /**
  * Metrics namespace the buildkite-agent-scaler publishes to, dimensioned by
  * {Org, Queue} — BOTH dimensions are required; querying Queue alone reads no
@@ -70,8 +70,8 @@ export function addBuildkiteAlarms(scope, params) {
         evaluationPeriods: 3,
         treatMissingData: TreatMissingData.NOT_BREACHING
     });
-    if (params.alarmSnsTopicArn !== undefined) {
-        const topic = Topic.fromTopicArn(scope, "BuildkiteAlarmTopic", params.alarmSnsTopicArn);
+    const topic = resolveAlertsTopic(scope, "BuildkiteAlarmTopic", params.alarmSnsTopicArn);
+    if (topic !== undefined) {
         heartbeatAlarm.addAlarmAction(new SnsAction(topic));
         queuedAlarm.addAlarmAction(new SnsAction(topic));
     }

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

@@ -1,4 +1,5 @@
-import { CfnOutput, Duration, Stack, Token } from "aws-cdk-lib";
+import { CfnOutput, Duration, RemovalPolicy, Stack, Token } from "aws-cdk-lib";
+import { Monitoring } from "aws-cdk-lib/aws-autoscaling";
 import { InstanceArchitecture, InstanceType, MachineImage, SubnetType } from "aws-cdk-lib/aws-ec2";
 import { PolicyStatement } from "aws-cdk-lib/aws-iam";
 import { Source } from "aws-cdk-lib/aws-s3-deployment";
@@ -8,8 +9,9 @@ import { Ec2Instance } from "../../../resources/aws/compute/ec2.js";
 import { SamApplication } from "../../../resources/aws/compute/samApplication.js";
 import { Policy } from "../../../resources/aws/iam/index.js";
 import { BucketDeployment, S3Bucket } from "../../../resources/aws/storage/index.js";
+import { createBuildkiteAlarms } from "../../../resources/aws/monitoring/index.js";
 import { applyCostAllocationTags } from "../../../utils/costAllocationTags.js";
-import { addBuildkiteAlarms } from "./alarms.js";
+import { resolveAlertsTopic } from "../../../utils/resolveAlertsTopic.js";
 import { buildAgentRole } from "./iam.js";
 import { BUILDKITE_STACK_PINS, resolvePinnedAmiId, resolveScalerSarApplicationArn } from "./pins.js";
 import { validateBuildkiteProps } from "./schema.js";
@@ -55,7 +57,10 @@ export class Buildkite extends Construct {
             })
         });
         const artifactBucket = new S3Bucket(this, `${id}ArtifactBucket`);
-        const managedSecretsBucket = new S3Bucket(this, `${id}ManagedSecretsBucket`);
+        // Secrets (SSH deploy keys, git credentials) must survive stack teardown
+        // and accidental overwrite; the artifact bucket is scratch output and
+        // keeps the wrapper's env-aware default (DESTROY + pre-empty off prod).
+        const managedSecretsBucket = new S3Bucket(this, `${id}ManagedSecretsBucket`, { versioned: true, removalPolicy: RemovalPolicy.RETAIN });
         if (config.fjallApiKeySsmParameterName !== undefined) {
             this.addFjallApiKeyEnvHook(id, managedSecretsBucket, config.fjallApiKeySsmParameterName, region);
         }
@@ -102,6 +107,12 @@ export class Buildkite extends Construct {
             userData,
             role: agentRole,
             ssmSessionPermissions: false,
+            // Upstream parity: EnableDetailedMonitoring defaults "false" in the
+            // pinned v6.68.1 template, and the wrapper's absent-default is DETAILED
+            // — omitting this silently deviated. The fleet's alarms and scaler run
+            // on Buildkite queue metrics, not EC2 metrics, so 1-minute granularity
+            // buys nothing here.
+            instanceMonitoring: Monitoring.BASIC,
             blockDevices: [
                 {
                     deviceName: "/dev/xvda",
@@ -163,12 +174,15 @@ export class Buildkite extends Construct {
                 costAllocationEnvironment: config.costAllocationEnvironment
             })
         });
-        addBuildkiteAlarms(this, {
+        const alertsTopic = resolveAlertsTopic(this, "BuildkiteAlarmTopic", config.alarmSnsTopicArn);
+        createBuildkiteAlarms({
+            scope: this,
             buildkiteOrgSlug: config.buildkiteOrgSlug,
             buildkiteQueue: config.buildkiteQueue,
             autoScalingGroupName: autoScalingGroup.autoScalingGroupName,
-            ...(config.alarmSnsTopicArn !== undefined && {
-                alarmSnsTopicArn: config.alarmSnsTopicArn
+            ...(alertsTopic !== undefined && { alarmTopic: alertsTopic }),
+            ...(config.applicationId !== undefined && {
+                applicationId: config.applicationId
             })
         });
         this.artifactBucketName = artifactBucket.bucketName;

package/dist/lib/patterns/aws/buildkite/factory.d.ts

@@ -0,0 +1,27 @@
+import { type Construct } from "constructs";
+import type App from "../../../app.js";
+import { Buildkite, type BuildkiteConstructProps } from "./buildkite.js";
+import type { BuildkitePropsInput } from "./schema.js";
+/**
+ * Thunk returned by `BuildkiteFactory.build` — materialised only by
+ * `App.addBuildkite`, which owns stack placement (the fleet has exactly one
+ * legal home, `${stackPrefix}Compute`; design
+ * `aiDocs/designs/2026-07-18-fjall-add-buildkite.md` § D2).
+ */
+export type BuildkiteFactoryFn = (app: App, scope: Construct) => Buildkite;
+/**
+ * Resolve construct props from plain-data input: VPC injection plus the three
+ * app-level defaults (cost-allocation environment, shared alarm topic,
+ * applicationId). Single source for both `App.addBuildkite` entry paths
+ * (design § D2) — explicit props always win.
+ */
+export declare function resolveBuildkiteConstructProps(app: App, props: BuildkitePropsInput): BuildkiteConstructProps;
+/**
+ * Factory for the self-hosted Buildkite agent fleet — the codemod add path
+ * emits `app.addBuildkite(BuildkiteFactory.build("Buildkite", { … }))`
+ * (design § D2/§ D3). Validation, the region guard, cost tags, and pinned-AMI
+ * resolution all live in the `Buildkite` constructor and fire on every path.
+ */
+export declare class BuildkiteFactory {
+    static build(id: string, props: BuildkitePropsInput): BuildkiteFactoryFn;
+}

package/dist/lib/patterns/aws/buildkite/factory.js

@@ -0,0 +1,39 @@
+import { SHARED_ALARM_TOPIC_EXPORT_NAME } from "../../../config/aws/alarmTopic.js";
+import { UNKNOWN_ENVIRONMENT } from "../../../utils/env.js";
+import { getConfig } from "../../../utils/getConfig.js";
+import { Buildkite } from "./buildkite.js";
+/**
+ * Resolve construct props from plain-data input: VPC injection plus the three
+ * app-level defaults (cost-allocation environment, shared alarm topic,
+ * applicationId). Single source for both `App.addBuildkite` entry paths
+ * (design § D2) — explicit props always win.
+ */
+export function resolveBuildkiteConstructProps(app, props) {
+    const configEnvironment = getConfig().environment;
+    const constructProps = { ...props, vpc: app.getVpc() };
+    // Post-spread injection so a caller-materialised `costAllocationEnvironment:
+    // undefined` counts as absent rather than clobbering the resolved value.
+    if (constructProps.costAllocationEnvironment === undefined &&
+        configEnvironment !== "" &&
+        configEnvironment !== UNKNOWN_ENVIRONMENT) {
+        constructProps.costAllocationEnvironment = configEnvironment;
+    }
+    if (constructProps.alarmSnsTopicArn === undefined) {
+        constructProps.alarmSnsTopicArn = `import:${SHARED_ALARM_TOPIC_EXPORT_NAME}`;
+    }
+    if (constructProps.applicationId === undefined) {
+        constructProps.applicationId = app.getName();
+    }
+    return constructProps;
+}
+/**
+ * Factory for the self-hosted Buildkite agent fleet — the codemod add path
+ * emits `app.addBuildkite(BuildkiteFactory.build("Buildkite", { … }))`
+ * (design § D2/§ D3). Validation, the region guard, cost tags, and pinned-AMI
+ * resolution all live in the `Buildkite` constructor and fire on every path.
+ */
+export class BuildkiteFactory {
+    static build(id, props) {
+        return (app, scope) => new Buildkite(scope, id, resolveBuildkiteConstructProps(app, props));
+    }
+}

package/dist/lib/patterns/aws/buildkite/iam.js

@@ -58,7 +58,8 @@ export const BUILDKITE_AGENT_IAM_ACTION_ALLOWLIST = [
  */
 export function buildAgentRole(scope, id, params) {
     return new Role(scope, id, {
-        description: "Buildkite agent instance role — allowlist-only, no deploy capability",
+        // IAM descriptions only accept [\t\n\r\x20-\x7E\xA1-\xFF] — no em-dashes
+        description: "Buildkite agent instance role - allowlist-only, no deploy capability",
         inlinePolicies: buildAgentPolicyDocuments(params),
         assumedBy: new CompositePrincipal(new ServicePrincipal("autoscaling.amazonaws.com"), new ServicePrincipal("ec2.amazonaws.com"))
     });
@@ -115,6 +116,10 @@ function buildAgentPolicyDocuments(params) {
         logging: new PolicyDocument({
             statements: [
                 new PolicyStatement({
+                    // PutRetentionPolicy pairs with ENABLE_EC2_LOG_RETENTION_POLICY
+                    // ='true' in the install part (userData.ts) — the booting instance
+                    // applies agentLogRetentionDays to the /buildkite/* groups. Remove
+                    // only together with that flag.
                     actions: [
                         "logs:CreateLogGroup",
                         "logs:CreateLogStream",

package/dist/lib/patterns/aws/buildkite/schema.d.ts

@@ -1,80 +1,8 @@
-import { z } from "zod";
 /**
- * Plain-data props for the `Buildkite` pattern, validated at construct time.
- * Deliberately CDK-free so the same schema can later back the customer
- * scaffold surface if the pattern is ever promoted to `PATTERN_TYPE_VALUES`
- * (design § D3 — promotion must be additive).
- *
- * Defaults encode the design's deploy-fleet posture
- * (`aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`):
- * on-demand-only (`spotCapacityPercentage` 0 — ASG mixed-instances has no
- * spot→on-demand fallback, and a spot reclaim mid-deploy is a rollback
- * incident, § D7), scale-to-zero, whole-instance agents, bounded instance
- * staleness, and no ECR / docker-login instance-level credentials (§ D9 —
- * deploy AWS access stays server-minted; the instance profile confers none).
+ * Buildkite props schema — re-export barrel. The canonical declaration lives
+ * in `@fjall/generator` (`src/schemas/buildkiteSchemas.ts`) so construct
+ * validation, the codemod fragment, and the LLM JSON schema all consume one
+ * source (design `aiDocs/designs/2026-07-18-fjall-add-buildkite.md` § D4).
+ * Do NOT redeclare here — the cross-package reference-identity test pins it.
  */
-export declare const BuildkitePropsSchema: z.ZodObject<{
-    buildkiteQueue: z.ZodString;
-    buildkiteOrgSlug: z.ZodString;
-    agentTokenSsmParameterName: z.ZodString;
-    agentTokenKmsKeyArn: z.ZodOptional<z.ZodString>;
-    fjallApiKeySsmParameterName: z.ZodOptional<z.ZodString>;
-    instanceType: z.ZodDefault<z.ZodString>;
-    agentVolumeSizeGib: z.ZodDefault<z.ZodNumber>;
-    agentMinInstances: z.ZodDefault<z.ZodNumber>;
-    agentMaxInstances: z.ZodDefault<z.ZodNumber>;
-    agentsPerInstance: z.ZodDefault<z.ZodNumber>;
-    spotCapacityPercentage: z.ZodDefault<z.ZodNumber>;
-    scaleInIdlePeriodSeconds: z.ZodDefault<z.ZodNumber>;
-    disconnectAfterUptimeSeconds: z.ZodDefault<z.ZodNumber>;
-    maxInstanceLifetimeDays: z.ZodDefault<z.ZodNumber>;
-    terminateInstanceAfterJob: z.ZodDefault<z.ZodBoolean>;
-    purgeBuildsOnDiskFull: z.ZodDefault<z.ZodBoolean>;
-    terminateInstanceOnDiskFull: z.ZodDefault<z.ZodBoolean>;
-    logRetentionDays: z.ZodDefault<z.ZodNumber>;
-    buildkiteAgentRelease: z.ZodDefault<z.ZodEnum<{
-        stable: "stable";
-        beta: "beta";
-        edge: "edge";
-    }>>;
-    buildkiteAgentTags: z.ZodDefault<z.ZodString>;
-    buildkiteAgentTimestampLines: z.ZodDefault<z.ZodBoolean>;
-    buildkiteAgentExperiments: z.ZodDefault<z.ZodString>;
-    buildkiteAgentTracingBackend: z.ZodDefault<z.ZodEnum<{
-        "": "";
-        datadog: "datadog";
-        opentelemetry: "opentelemetry";
-    }>>;
-    buildkiteAgentCancelGracePeriodSeconds: z.ZodDefault<z.ZodNumber>;
-    enableSecretsPlugin: z.ZodDefault<z.ZodBoolean>;
-    enableEcrPlugin: z.ZodDefault<z.ZodBoolean>;
-    enableDockerLoginPlugin: z.ZodDefault<z.ZodBoolean>;
-    enableDockerUserNamespaceRemap: z.ZodDefault<z.ZodBoolean>;
-    enableDockerExperimental: z.ZodDefault<z.ZodBoolean>;
-    dockerNetworkingProtocol: z.ZodDefault<z.ZodEnum<{
-        ipv4: "ipv4";
-        dualstack: "dualstack";
-    }>>;
-    enableInstanceStorage: z.ZodDefault<z.ZodBoolean>;
-    mountTmpfsAtTmp: z.ZodDefault<z.ZodBoolean>;
-    buildkiteAgentEnableGitMirrors: z.ZodDefault<z.ZodBoolean>;
-    bootstrapScriptUrl: z.ZodDefault<z.ZodString>;
-    agentEnvFileUrl: z.ZodDefault<z.ZodString>;
-    scalerEventSchedulePeriod: z.ZodDefault<z.ZodString>;
-    scalerMinPollInterval: z.ZodDefault<z.ZodString>;
-    scaleOutFactor: z.ZodDefault<z.ZodString>;
-    scaleOutWaitingForJobs: z.ZodDefault<z.ZodBoolean>;
-    rolePermissionsBoundaryArn: z.ZodOptional<z.ZodString>;
-    alarmSnsTopicArn: z.ZodOptional<z.ZodString>;
-    costAllocationEnvironment: z.ZodOptional<z.ZodString>;
-    costAllocationOwner: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-export type BuildkiteProps = z.infer<typeof BuildkitePropsSchema>;
-/** Caller-facing shape: fields with defaults are optional at the call site. */
-export type BuildkitePropsInput = z.input<typeof BuildkitePropsSchema>;
-/**
- * Validate + default the plain-data props at construct time. Throws a
- * synth-time error listing every violation — the pattern's constructor is the
- * validation boundary, mirroring `ClickHouseDatabase`'s Stage-1 shape.
- */
-export declare function validateBuildkiteProps(props: BuildkitePropsInput): BuildkiteProps;
+export { BuildkitePropsObjectSchema, BuildkitePropsSchema, validateBuildkiteProps, type BuildkiteProps, type BuildkitePropsInput, type BuildkitePropsObject } from "@fjall/generator";

package/dist/lib/patterns/aws/buildkite/schema.js

@@ -1,148 +1,8 @@
-import { z } from "zod";
 /**
- * Plain-data props for the `Buildkite` pattern, validated at construct time.
- * Deliberately CDK-free so the same schema can later back the customer
- * scaffold surface if the pattern is ever promoted to `PATTERN_TYPE_VALUES`
- * (design § D3 — promotion must be additive).
- *
- * Defaults encode the design's deploy-fleet posture
- * (`aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`):
- * on-demand-only (`spotCapacityPercentage` 0 — ASG mixed-instances has no
- * spot→on-demand fallback, and a spot reclaim mid-deploy is a rollback
- * incident, § D7), scale-to-zero, whole-instance agents, bounded instance
- * staleness, and no ECR / docker-login instance-level credentials (§ D9 —
- * deploy AWS access stays server-minted; the instance profile confers none).
+ * Buildkite props schema — re-export barrel. The canonical declaration lives
+ * in `@fjall/generator` (`src/schemas/buildkiteSchemas.ts`) so construct
+ * validation, the codemod fragment, and the LLM JSON schema all consume one
+ * source (design `aiDocs/designs/2026-07-18-fjall-add-buildkite.md` § D4).
+ * Do NOT redeclare here — the cross-package reference-identity test pins it.
  */
-export const BuildkitePropsSchema = z
-    .object({
-    /** Buildkite queue this fleet serves (cluster-scoped via the token). */
-    buildkiteQueue: z
-        .string()
-        .min(1, "buildkiteQueue cannot be empty")
-        .max(100)
-        .regex(/^[a-zA-Z0-9-_]+$/, "buildkiteQueue must be alphanumeric with hyphens/underscores"),
-    /**
-     * Buildkite organisation slug (e.g. `fjall-tech`). The
-     * buildkite-agent-scaler publishes its CloudWatch metrics dimensioned by
-     * {Org, Queue} — the fleet's alarms must query the same pair or they read
-     * no data at all (heartbeat permanently ALARM, queued-with-zero-capacity
-     * permanently inert).
-     */
-    buildkiteOrgSlug: z
-        .string()
-        .min(1, "buildkiteOrgSlug cannot be empty")
-        .max(100)
-        .regex(/^[a-z0-9-]+$/, "buildkiteOrgSlug must be a lowercase Buildkite organisation slug"),
-    /**
-     * Name of the pre-provisioned SSM SecureString holding the cluster-scoped
-     * agent token (e.g. `/Buildkite/agents/agent-token`). Provisioned
-     * out-of-band via `fjall secrets` tooling — the construct receives the
-     * identifier only; no secret value ever transits synth (design § D4).
-     */
-    agentTokenSsmParameterName: z
-        .string()
-        .min(2)
-        .regex(/^\//, "agentTokenSsmParameterName must be a full path (leading /)"),
-    /**
-     * KMS key ARN encrypting the agent-token parameter, when a customer
-     * managed key is used. Omit for the AWS-managed `aws/ssm` key.
-     */
-    agentTokenKmsKeyArn: z.string().min(1).optional(),
-    /**
-     * Name of the SSM SecureString holding FJALL_API_KEY. When set, the
-     * construct ships a per-job `env` hook into the managed secrets bucket
-     * that reads the parameter at job start (rotation takes effect on the
-     * next job, no instance replacement — design § D4(iii)) and grants the
-     * instance profile read on exactly this parameter.
-     */
-    fjallApiKeySsmParameterName: z
-        .string()
-        .min(2)
-        .regex(/^\//, "fjallApiKeySsmParameterName must be a full path (leading /)")
-        .optional(),
-    /** EC2 instance type. Graviton default per design § D7. */
-    instanceType: z.string().min(1).default("c8g.xlarge"),
-    agentVolumeSizeGib: z.number().int().min(20).max(1000).default(250),
-    agentMinInstances: z.number().int().min(0).default(0),
-    agentMaxInstances: z.number().int().min(1).default(2),
-    agentsPerInstance: z.number().int().min(1).default(1),
-    /**
-     * Percentage of capacity on spot. Deploy fleets MUST stay 0 (on-demand
-     * only): no spot→on-demand fallback mechanism exists, and a reclaim
-     * mid-deploy lands in the rollback-wedge class (design § D7). Non-zero is
-     * for Phase-2 CI fleets running idempotent, auto-retried jobs.
-     */
-    spotCapacityPercentage: z.number().int().min(0).max(100).default(0),
-    /** Agent-driven scale-in: idle seconds before an instance self-terminates. */
-    scaleInIdlePeriodSeconds: z.number().int().min(60).default(600),
-    /** Bounded instance staleness; also caps stale-token propagation (§ D5). */
-    disconnectAfterUptimeSeconds: z.number().int().min(3600).default(86_400),
-    maxInstanceLifetimeDays: z.number().int().min(1).max(365).default(7),
-    terminateInstanceAfterJob: z.boolean().default(false),
-    purgeBuildsOnDiskFull: z.boolean().default(true),
-    terminateInstanceOnDiskFull: z.boolean().default(false),
-    /** CloudWatch retention for the scaler's log group (days). */
-    logRetentionDays: z.number().int().min(1).default(30),
-    buildkiteAgentRelease: z.enum(["stable", "beta", "edge"]).default("stable"),
-    buildkiteAgentTags: z.string().default(""),
-    buildkiteAgentTimestampLines: z.boolean().default(false),
-    buildkiteAgentExperiments: z.string().default(""),
-    buildkiteAgentTracingBackend: z
-        .enum(["", "datadog", "opentelemetry"])
-        .default(""),
-    buildkiteAgentCancelGracePeriodSeconds: z
-        .number()
-        .int()
-        .min(10)
-        .default(60),
-    /** S3 secrets-hooks plugin — required for the FJALL_API_KEY env hook. */
-    enableSecretsPlugin: z.boolean().default(true),
-    /**
-     * ECR + docker-login plugins default OFF: the instance profile carries no
-     * registry credentials (design § D9); deploy jobs authenticate through
-     * server-minted credentials exactly as on hosted agents.
-     */
-    enableEcrPlugin: z.boolean().default(false),
-    enableDockerLoginPlugin: z.boolean().default(false),
-    enableDockerUserNamespaceRemap: z.boolean().default(true),
-    enableDockerExperimental: z.boolean().default(false),
-    dockerNetworkingProtocol: z.enum(["ipv4", "dualstack"]).default("ipv4"),
-    enableInstanceStorage: z.boolean().default(false),
-    mountTmpfsAtTmp: z.boolean().default(true),
-    buildkiteAgentEnableGitMirrors: z.boolean().default(false),
-    bootstrapScriptUrl: z.string().default(""),
-    agentEnvFileUrl: z.string().default(""),
-    scalerEventSchedulePeriod: z.string().min(1).default("1 minute"),
-    scalerMinPollInterval: z.string().min(1).default("10s"),
-    scaleOutFactor: z.string().min(1).default("1.0"),
-    scaleOutWaitingForJobs: z.boolean().default(false),
-    /** IAM permissions boundary for the scaler's roles; emitted only when set. */
-    rolePermissionsBoundaryArn: z.string().min(1).optional(),
-    /**
-     * SNS topic receiving the fleet's two alarms (scaler heartbeat + queued
-     * with zero capacity — design § D14). Omit to create the alarms without
-     * actions (visible on the console, silent).
-     */
-    alarmSnsTopicArn: z.string().min(1).optional(),
-    costAllocationEnvironment: z.string().min(1).optional(),
-    costAllocationOwner: z.string().min(1).optional()
-})
-    .strict()
-    .refine((props) => props.agentMinInstances <= props.agentMaxInstances, {
-    message: "agentMinInstances must be <= agentMaxInstances"
-});
-/**
- * Validate + default the plain-data props at construct time. Throws a
- * synth-time error listing every violation — the pattern's constructor is the
- * validation boundary, mirroring `ClickHouseDatabase`'s Stage-1 shape.
- */
-export function validateBuildkiteProps(props) {
-    const result = BuildkitePropsSchema.safeParse(props);
-    if (!result.success) {
-        const details = result.error.issues
-            .map((issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`)
-            .join("\n");
-        throw new Error(`Buildkite: invalid props:\n${details}`);
-    }
-    return result.data;
-}
+export { BuildkitePropsObjectSchema, BuildkitePropsSchema, validateBuildkiteProps } from "@fjall/generator";

package/dist/lib/patterns/aws/buildkite/userData.d.ts

@@ -42,7 +42,7 @@ export declare function buildBuildkiteDockerCommands(props: BuildkiteProps): str
  * `bk-install-elastic-stack.sh`, mirroring the upstream block key-for-key in
  * upstream order (so a fixture-bump diff reads line-by-line). Keys with no
  * schema knob carry the upstream v6.68.1 parameter default verbatim, with
- * three deliberate deviations:
+ * four deliberate deviations:
  *
  * - `BUILDKITE_S3_ACL`: our artifact bucket is BucketOwnerEnforced (ACLs
  *   disabled), where S3 rejects every canned ACL EXCEPT
@@ -54,5 +54,16 @@ export declare function buildBuildkiteDockerCommands(props: BuildkiteProps): str
  *   is out of scope for the Phase-1 deploy fleet; a future signing knob must
  *   land WITH the kms:Sign/Verify/GetPublicKey grants it needs (the prior
  *   knob shipped without them — a dead toggle that broke agents when set).
+ * - `ENABLE_EC2_LOG_RETENTION_POLICY`: hard-pinned `true` (upstream default
+ *   `false`, "preserve all logs"). Fjall's log-group lifecycle posture is
+ *   bounded retention everywhere: each booting instance applies
+ *   `agentLogRetentionDays` to the agent-created `/buildkite/*` groups via
+ *   the instance role's `logs:PutRetentionPolicy` grant (which this flag
+ *   makes live — it was stranded while `false`). Retro-applies to existing
+ *   groups on the next boot after enabling, expiring events older than the
+ *   window. Residual: runtime-created groups stay untagged — the namespace
+ *   is account-global (shared across fleets and stacks), so CFN pre-creation
+ *   would fight cross-stack ownership; cost exposure is bounded by the
+ *   retention itself.
  */
 export declare function buildBuildkiteInstallCommands(props: BuildkiteProps, context: BuildkiteUserDataContext): string[];

package/dist/lib/patterns/aws/buildkite/userData.js

@@ -149,7 +149,7 @@ export function buildBuildkiteDockerCommands(props) {
  * `bk-install-elastic-stack.sh`, mirroring the upstream block key-for-key in
  * upstream order (so a fixture-bump diff reads line-by-line). Keys with no
  * schema knob carry the upstream v6.68.1 parameter default verbatim, with
- * three deliberate deviations:
+ * four deliberate deviations:
  *
  * - `BUILDKITE_S3_ACL`: our artifact bucket is BucketOwnerEnforced (ACLs
  *   disabled), where S3 rejects every canned ACL EXCEPT
@@ -161,6 +161,17 @@ export function buildBuildkiteDockerCommands(props) {
  *   is out of scope for the Phase-1 deploy fleet; a future signing knob must
  *   land WITH the kms:Sign/Verify/GetPublicKey grants it needs (the prior
  *   knob shipped without them — a dead toggle that broke agents when set).
+ * - `ENABLE_EC2_LOG_RETENTION_POLICY`: hard-pinned `true` (upstream default
+ *   `false`, "preserve all logs"). Fjall's log-group lifecycle posture is
+ *   bounded retention everywhere: each booting instance applies
+ *   `agentLogRetentionDays` to the agent-created `/buildkite/*` groups via
+ *   the instance role's `logs:PutRetentionPolicy` grant (which this flag
+ *   makes live — it was stranded while `false`). Retro-applies to existing
+ *   groups on the next boot after enabling, expiring events older than the
+ *   window. Residual: runtime-created groups stay untagged — the namespace
+ *   is account-global (shared across fleets and stacks), so CFN pre-creation
+ *   would fight cross-stack ownership; cost exposure is bounded by the
+ *   retention itself.
  */
 export function buildBuildkiteInstallCommands(props, context) {
     return [
@@ -219,8 +230,8 @@ export function buildBuildkiteInstallCommands(props, context) {
         "RESOURCE_LIMITS_CPU_WEIGHT='100' \\",
         "RESOURCE_LIMITS_CPU_QUOTA='90%' \\",
         "RESOURCE_LIMITS_IO_WEIGHT='80' \\",
-        "ENABLE_EC2_LOG_RETENTION_POLICY='false' \\",
-        "EC2_LOG_RETENTION_DAYS='7' \\",
+        "ENABLE_EC2_LOG_RETENTION_POLICY='true' \\",
+        `EC2_LOG_RETENTION_DAYS='${props.agentLogRetentionDays}' \\`,
         "/usr/local/bin/bk-install-elastic-stack.sh"
     ];
 }

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

@@ -7,6 +7,6 @@
 export { Buildkite, FJALL_ENV_HOOK_OBJECT_KEY, buildFjallApiKeyEnvHookScript, type BuildkiteConstructProps } from "./buildkite/buildkite.js";
 export { BUILDKITE_AMI_OWNER_ACCOUNT_ID, BUILDKITE_CPU_ARCHITECTURES, BUILDKITE_STACK_PINS, resolvePinnedAmiId, resolveScalerSarApplicationArn, type BuildkiteCpuArchitecture } from "./buildkite/pins.js";
 export { BuildkitePropsSchema, validateBuildkiteProps, type BuildkiteProps, type BuildkitePropsInput } from "./buildkite/schema.js";
+export { BuildkiteFactory, type BuildkiteFactoryFn } from "./buildkite/factory.js";
 export { BUILDKITE_AGENT_IAM_ACTION_ALLOWLIST, buildAgentRole, type BuildkiteAgentRoleParams } from "./buildkite/iam.js";
 export { BUILDKITE_DOCKER_PART_ENV_KEYS, BUILDKITE_MOUNT_PART_ENV_KEYS, BUILDKITE_USER_DATA_ENV_KEYS, buildBuildkiteDockerCommands, buildBuildkiteInstallCommands, buildBuildkiteMountCommands, buildBuildkiteUserData, type BuildkiteUserDataContext } from "./buildkite/userData.js";
-export { addBuildkiteAlarms, type BuildkiteAlarmParams } from "./buildkite/alarms.js";

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

@@ -7,6 +7,6 @@
 export { Buildkite, FJALL_ENV_HOOK_OBJECT_KEY, buildFjallApiKeyEnvHookScript } from "./buildkite/buildkite.js";
 export { BUILDKITE_AMI_OWNER_ACCOUNT_ID, BUILDKITE_CPU_ARCHITECTURES, BUILDKITE_STACK_PINS, resolvePinnedAmiId, resolveScalerSarApplicationArn } from "./buildkite/pins.js";
 export { BuildkitePropsSchema, validateBuildkiteProps } from "./buildkite/schema.js";
+export { BuildkiteFactory } from "./buildkite/factory.js";
 export { BUILDKITE_AGENT_IAM_ACTION_ALLOWLIST, buildAgentRole } from "./buildkite/iam.js";
 export { BUILDKITE_DOCKER_PART_ENV_KEYS, BUILDKITE_MOUNT_PART_ENV_KEYS, BUILDKITE_USER_DATA_ENV_KEYS, buildBuildkiteDockerCommands, buildBuildkiteInstallCommands, buildBuildkiteMountCommands, buildBuildkiteUserData } from "./buildkite/userData.js";
-export { addBuildkiteAlarms } from "./buildkite/alarms.js";

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

@@ -40,27 +40,38 @@ export interface IDevSubstrateProps {
     readonly adoptSlotEcr?: boolean;
     /**
      * Deploy phase for the R2 two-step cert-hang guard. `"zone"` synthesises the
-     * `dev.<appDomain>` child zone + cross-account NS delegation only; `"full"`
-     * additionally builds the wildcard cert + :443 listener (A6) — deploy that
-     * only after the delegated NS has propagated, else ACM DNS-validation hangs.
-     * Defaults to `"full"`. Inert unless `domain` is set.
+     * `devDomain` zone + cross-account NS delegation only; `"full"` additionally
+     * builds the wildcard cert + :443 listener (A6) — deploy that only after the
+     * delegated NS has propagated, else ACM DNS-validation hangs. Defaults to
+     * `"full"`. Inert unless `domain` is set.
      */
     readonly phase?: DomainDeployPhase;
     /**
-     * Public domain the substrate hangs a `dev.<appDomain>` child zone under. When
-     * omitted, the substrate stands up no zone/cert (early milestone — G2 reaches
-     * slots via `curl --resolve`).
+     * The zone slots serve under — an EXPLICIT name (`devDomain`, e.g.
+     * `development.fjall.io`), never derived by prefixing. When omitted, the
+     * substrate stands up no zone/cert (early milestone — G2 reaches slots via
+     * `curl --resolve`).
      *
-     * `parentDelegationRoleArn`, when present, wires the same-org **Case-1** in-stack
-     * NS delegation (design VD2-a): the child stack's `CrossAccountZoneDelegationRecord`
-     * assumes the parent account's `DelegationRole` by LITERAL ARN and UPSERTs the
-     * child NS into the parent zone. Omit it for a plain externally-owned parent
-     * (Case 3 — manual one-off delegation) or a connected different-org parent
-     * (Case 2 — worker UPSERT, B3b, deferred): the substrate then emits only the
-     * zone + its NS export for out-of-band delegation.
+     * Adopt mode (`hostedZoneId` present): the substrate adopts an existing zone
+     * (e.g. the account's delegated Domain) by import — no zone resource, no
+     * delegation record, no NS export. Mutually exclusive with `parentDomain` /
+     * `parentDelegationRoleArn`.
+     *
+     * Create mode (no `hostedZoneId`): the substrate creates the `devDomain`
+     * zone. `parentDelegationRoleArn`, when present, wires the same-org **Case-1**
+     * in-stack NS delegation (design VD2-a): the child stack's
+     * `CrossAccountZoneDelegationRecord` assumes the parent account's
+     * `DelegationRole` by LITERAL ARN and UPSERTs the child NS into the
+     * `parentDomain` zone — `parentDomain` (a proper DNS suffix of `devDomain`)
+     * MUST accompany it. Omit both for a plain externally-owned parent (Case 3 —
+     * manual one-off delegation) or a connected different-org parent (Case 2 —
+     * worker UPSERT, B3b, deferred): the substrate then emits only the zone + its
+     * NS export for out-of-band delegation.
      */
     readonly domain?: {
-        readonly appDomain: string;
+        readonly devDomain: string;
+        readonly hostedZoneId?: string;
+        readonly parentDomain?: string;
         readonly parentDelegationRoleArn?: string;
     };
 }

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

@@ -4,6 +4,7 @@ import { Cluster } from "aws-cdk-lib/aws-ecs";
 import { Repository } 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 { SqsDestination } from "aws-cdk-lib/aws-s3-notifications";
 import { Construct } from "constructs";
 import { readFileSync } from "node:fs";
@@ -48,7 +49,7 @@ const DEV_SUBSTRATE_WAKER_ID = "DevSubstrateWaker";
 const DEV_SUBSTRATE_WAKER_TG_ID = "DevSubstrateWakerTargetGroup";
 const DEV_SUBSTRATE_WAKER_SOURCE_FILE = "devSubstrate.waker.source.cjs";
 const DEV_SUBSTRATE_WAKER_TIMEOUT_SECONDS = 30;
-/** Construct ids for the substrate's delegated `dev.<appDomain>` child zone. */
+/** Construct ids for the substrate's `devDomain` slot zone (created or adopted). */
 const DEV_SUBSTRATE_ZONE_ID = "DevSubstrateZone";
 const DEV_SUBSTRATE_DELEGATION_ID = "DevSubstrateDelegation";
 const DEV_SUBSTRATE_PARENT_ROLE_ID = "DevSubstrateParentDelegationRole";
@@ -306,32 +307,51 @@ export class DevSubstrate extends Construct {
     #createDomain(props, loadBalancer) {
         if (props.domain === undefined)
             return {};
-        const { appDomain, parentDelegationRoleArn } = props.domain;
-        const childZoneName = `dev.${appDomain}`;
-        // The delegated child zone: createDelegationRole:false because the PARENT
-        // account owns the delegation role (this is the child). The HostedZone
-        // wrapper's create path auto-emits the `<zone>-nameservers` CFN export the
-        // parent consumes to point NS records at us — no manual export needed.
-        const childZone = new HostedZone(this, DEV_SUBSTRATE_ZONE_ID, {
-            zoneName: childZoneName,
-            createDelegationRole: false
-        });
-        // Case-1 same-org delegation fires only when a parent role ARN is supplied.
-        // The in-stack custom resource assumes the parent account's DelegationRole by
-        // LITERAL ARN (Role.fromRoleArn) — NOT Fn.importValue, which resolves
-        // same-account only and is exactly why the DomainDelegation pattern cannot go
-        // cross-account (design VD2-a). The parent DelegationRole trusts the whole
-        // org (OrganizationPrincipal), so a sibling dev account can assume it. Absent
-        // ARN ⇒ Case 2 (worker UPSERT, B3b) / Case 3 (manual), handled out of band:
-        // the zone + NS export above is all the substrate emits.
-        if (parentDelegationRoleArn !== undefined) {
-            const parentRole = Role.fromRoleArn(this, DEV_SUBSTRATE_PARENT_ROLE_ID, parentDelegationRoleArn);
-            new CrossAccountDelegationRecord(this, DEV_SUBSTRATE_DELEGATION_ID, {
-                delegationRole: parentRole,
-                delegatedZone: childZone.hostedZone,
-                delegatedZoneName: childZoneName,
-                parentHostedZoneName: appDomain
+        const { devDomain, hostedZoneId, parentDomain, parentDelegationRoleArn } = props.domain;
+        const childZoneName = devDomain;
+        let childZone;
+        if (hostedZoneId !== undefined) {
+            // Adopt mode: import only — no zone resource, no delegation record, no NS
+            // export (the zone's NS was delegated when the account Domain deployed).
+            // Plain CDK import, NOT the HostedZone wrapper: its import path re-emits
+            // the global `<zone>-hosted-zone-id` export, colliding with the owning
+            // Domain stack's.
+            childZone = PublicHostedZone.fromHostedZoneAttributes(this, DEV_SUBSTRATE_ZONE_ID, { hostedZoneId, zoneName: childZoneName });
+        }
+        else {
+            // Create mode: createDelegationRole:false because the PARENT account owns
+            // the delegation role (this is the child). The HostedZone wrapper's create
+            // path auto-emits the `<zone>-nameservers` CFN export the parent consumes
+            // to point NS records at us — no manual export needed.
+            const createdZone = new HostedZone(this, DEV_SUBSTRATE_ZONE_ID, {
+                zoneName: childZoneName,
+                createDelegationRole: false
             });
+            childZone = createdZone.hostedZone;
+            // Case-1 same-org delegation fires only when a parent role ARN is supplied.
+            // The in-stack custom resource assumes the parent account's DelegationRole by
+            // LITERAL ARN (Role.fromRoleArn) — NOT Fn.importValue, which resolves
+            // same-account only and is exactly why the DomainDelegation pattern cannot go
+            // cross-account (design VD2-a). The parent DelegationRole trusts the whole
+            // org (OrganizationPrincipal), so a sibling dev account can assume it. Absent
+            // ARN ⇒ Case 2 (worker UPSERT, B3b) / Case 3 (manual), handled out of band:
+            // the zone + NS export above is all the substrate emits.
+            if (parentDelegationRoleArn !== undefined) {
+                // Re-checked here because direct construct calls bypass the Zod schema.
+                if (parentDomain === undefined) {
+                    throw new Error(`DevSubstrate domain "${devDomain}": parentDelegationRoleArn was ` +
+                        `supplied without parentDomain. Set domain.parentDomain to the ` +
+                        `parent zone the DelegationRole belongs to (a proper DNS suffix ` +
+                        `of devDomain), or omit parentDelegationRoleArn.`);
+                }
+                const parentRole = Role.fromRoleArn(this, DEV_SUBSTRATE_PARENT_ROLE_ID, parentDelegationRoleArn);
+                new CrossAccountDelegationRecord(this, DEV_SUBSTRATE_DELEGATION_ID, {
+                    delegationRole: parentRole,
+                    delegatedZone: childZone,
+                    delegatedZoneName: childZoneName,
+                    parentHostedZoneName: parentDomain
+                });
+            }
         }
         // 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.
@@ -342,7 +362,7 @@ export class DevSubstrate extends Construct {
         // would otherwise render an invalid CFN export name.
         const certificate = new DomainCertificate(this, DEV_SUBSTRATE_CERT_ID, {
             domainName: `*.${childZoneName}`,
-            hostedZone: childZone.hostedZone,
+            hostedZone: childZone,
             exportCertificateArn: false
         });
         // Unconditional 404 as on :80 (per-slot rules attach out of band, §5.4). open

package/dist/lib/resources/aws/monitoring/buildkiteAlarms.d.ts

@@ -0,0 +1,29 @@
+import { Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { ITopic } from "aws-cdk-lib/aws-sns";
+import type { Construct } from "constructs";
+export interface BuildkiteAlarmsProps {
+    scope: Construct;
+    buildkiteOrgSlug: string;
+    buildkiteQueue: string;
+    autoScalingGroupName: string;
+    /**
+     * Omitted → the alarms exist on the console but page nobody. Unlike the
+     * sibling builders the topic is optional: `App.addBuildkite` defaults it to
+     * the shared platform topic, and a bare construct must still synth.
+     */
+    alarmTopic?: ITopic;
+    applicationId?: string;
+}
+/**
+ * The fleet's two Phase-1 alarms (design § D14) — the "~zero babysitting"
+ * posture is honest only with these:
+ *
+ * 1. Scaler heartbeat — `ScheduledJobsCount` goes MISSING for 15 minutes.
+ *    The scaler publishes every poll, so metric absence means the scaler
+ *    Lambda is dead or failing; `treatMissingData: BREACHING` is the alarm's
+ *    entire mechanism.
+ * 2. Queued with zero capacity — jobs scheduled while the ASG has no
+ *    in-service instances for 15 minutes: the fleet cannot boot (AMI gone,
+ *    quota, subnet failure) while work is waiting.
+ */
+export declare function createBuildkiteAlarms(props: BuildkiteAlarmsProps): Alarm[];

package/dist/lib/resources/aws/monitoring/buildkiteAlarms.js

@@ -0,0 +1,90 @@
+import { Duration } from "aws-cdk-lib";
+import { Alarm, ComparisonOperator, MathExpression, Metric, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+import { SnsAction } from "aws-cdk-lib/aws-cloudwatch-actions";
+import { buildAlarmDescription, registerAlarm, tagAlarmsWithApplicationId } from "./alarmDefaults.js";
+/**
+ * Metrics namespace the buildkite-agent-scaler publishes to, dimensioned by
+ * {Org, Queue} — BOTH dimensions are required; querying Queue alone reads no
+ * data (CloudWatch dimension matching is exact-set), leaving the heartbeat
+ * permanently ALARM and the queued alarm permanently inert. Phase-1b rollout
+ * gate: verify both metrics carry data after the first build before trusting
+ * the alarms (design § D13/D14) — a namespace/dimension mismatch here is
+ * invisible to the synth tests.
+ */
+const SCALER_METRICS_NAMESPACE = "Buildkite";
+/**
+ * The fleet's two Phase-1 alarms (design § D14) — the "~zero babysitting"
+ * posture is honest only with these:
+ *
+ * 1. Scaler heartbeat — `ScheduledJobsCount` goes MISSING for 15 minutes.
+ *    The scaler publishes every poll, so metric absence means the scaler
+ *    Lambda is dead or failing; `treatMissingData: BREACHING` is the alarm's
+ *    entire mechanism.
+ * 2. Queued with zero capacity — jobs scheduled while the ASG has no
+ *    in-service instances for 15 minutes: the fleet cannot boot (AMI gone,
+ *    quota, subnet failure) while work is waiting.
+ */
+export function createBuildkiteAlarms(props) {
+    const { scope, buildkiteOrgSlug, buildkiteQueue, autoScalingGroupName, alarmTopic, applicationId } = props;
+    const alarms = [];
+    const snsAction = alarmTopic !== undefined ? new SnsAction(alarmTopic) : undefined;
+    const scheduledJobs = new Metric({
+        namespace: SCALER_METRICS_NAMESPACE,
+        metricName: "ScheduledJobsCount",
+        dimensionsMap: {
+            Org: buildkiteOrgSlug,
+            Queue: buildkiteQueue
+        },
+        statistic: "Maximum",
+        period: Duration.minutes(5)
+    });
+    const heartbeatAlarm = new Alarm(scope, "ScalerHeartbeatAlarm", {
+        alarmDescription: buildAlarmDescription(`Buildkite scaler for queue '${buildkiteQueue}' has stopped ` +
+            "publishing metrics — scaler Lambda dead or erroring. Jobs will " +
+            "queue with no scale-out.", applicationId),
+        metric: scheduledJobs,
+        comparisonOperator: ComparisonOperator.LESS_THAN_THRESHOLD,
+        threshold: 0,
+        evaluationPeriods: 3,
+        treatMissingData: TreatMissingData.BREACHING
+    });
+    if (snsAction !== undefined) {
+        registerAlarm(heartbeatAlarm, snsAction, alarms);
+    }
+    else {
+        alarms.push(heartbeatAlarm);
+    }
+    const inServiceInstances = new Metric({
+        namespace: "AWS/AutoScaling",
+        metricName: "GroupInServiceInstances",
+        dimensionsMap: { AutoScalingGroupName: autoScalingGroupName },
+        statistic: "Maximum",
+        period: Duration.minutes(5)
+    });
+    const queuedWithZeroCapacity = new MathExpression({
+        expression: "IF(scheduled > 0 AND inService == 0, 1, 0)",
+        usingMetrics: {
+            scheduled: scheduledJobs,
+            inService: inServiceInstances
+        },
+        period: Duration.minutes(5)
+    });
+    const queuedAlarm = new Alarm(scope, "QueuedWithZeroCapacityAlarm", {
+        alarmDescription: buildAlarmDescription(`Buildkite queue '${buildkiteQueue}' has scheduled jobs but zero ` +
+            "in-service agents for 15 minutes — the fleet cannot boot (AMI, " +
+            "quota, or subnet failure) while work waits.", applicationId),
+        metric: queuedWithZeroCapacity,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+        threshold: 1,
+        evaluationPeriods: 3,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    if (snsAction !== undefined) {
+        registerAlarm(queuedAlarm, snsAction, alarms);
+    }
+    else {
+        alarms.push(queuedAlarm);
+    }
+    tagAlarmsWithApplicationId(alarms, applicationId);
+    return alarms;
+}

package/dist/lib/resources/aws/monitoring/index.d.ts

@@ -4,5 +4,6 @@ export { createRdsAlarms, type RdsAlarmThresholds, type RdsAlarmsProps } from ".
 export { createLambdaAlarms, type LambdaAlarmThresholds, type LambdaAlarmsProps } from "./lambdaAlarms.js";
 export { createScheduleAlarms, type ScheduleAlarmThresholds, type CreateScheduleAlarmsProps } from "./scheduleAlarms.js";
 export { createClickHouseAlarms, type ClickHouseAlarmThresholds, type ClickHouseAlarmsProps } from "./clickhouseAlarms.js";
+export { createBuildkiteAlarms, type BuildkiteAlarmsProps } from "./buildkiteAlarms.js";
 export { createLogPatternAlarms, type LogPatternAlarmSpec, type LogPatternAlarmsProps } from "./logPatternAlarms.js";
 export { METRIC_NAMESPACE, type MetricNamespace } from "./metricNamespaces.js";

package/dist/lib/resources/aws/monitoring/index.js

@@ -4,5 +4,6 @@ export { createRdsAlarms } from "./rdsAlarms.js";
 export { createLambdaAlarms } from "./lambdaAlarms.js";
 export { createScheduleAlarms } from "./scheduleAlarms.js";
 export { createClickHouseAlarms } from "./clickhouseAlarms.js";
+export { createBuildkiteAlarms } from "./buildkiteAlarms.js";
 export { createLogPatternAlarms } from "./logPatternAlarms.js";
 export { METRIC_NAMESPACE } from "./metricNamespaces.js";

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

@@ -13,6 +13,9 @@ export class HostedZoneFactory {
         return new HostedZone(stack.getStack(), `${safeZone}HostedZone`, {
             hostedZoneId,
             zoneName,
+            // BYO app-stack imports never mint the role: its fixed RoleName would
+            // collide with the domain stack's own DelegationRole in the same account.
+            createDelegationRole: false,
             costAllocationEnvironment: opts?.costAllocationEnvironment,
             costAllocationDomain: opts?.costAllocationDomain,
             description: opts?.description
@@ -56,25 +59,6 @@ export class HostedZone extends Construct {
                 value: Fn.join(",", created.hostedZoneNameServers ?? []),
                 exportName: exportNames.nameservers
             });
-            // 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).
-            const inOrganisation = resolveOrgId(this.node) !== undefined;
-            if (props.createDelegationRole === true && !inOrganisation) {
-                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) {
-                this.delegationRole = new DelegationRole(this, `${safeZone}DelegationRole`, {
-                    zoneName: props.zoneName,
-                    hostedZone: created,
-                    organisationIdExportName: props.organisationIdExportName,
-                    costAllocationEnvironment: props.costAllocationEnvironment,
-                    costAllocationDomain: props.costAllocationDomain
-                });
-            }
         }
         else {
             // Import path — `fromHostedZoneAttributes` creates a reference, not a
@@ -88,6 +72,26 @@ 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).
+        // Runs for created AND adopted zones — `grantDelegation` is on IHostedZone.
+        const inOrganisation = resolveOrgId(this.node) !== undefined;
+        if (props.createDelegationRole === true && !inOrganisation) {
+            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) {
+            this.delegationRole = new DelegationRole(this, `${safeZone}DelegationRole`, {
+                zoneName: props.zoneName,
+                hostedZone: this.hostedZone,
+                organisationIdExportName: props.organisationIdExportName,
+                costAllocationEnvironment: props.costAllocationEnvironment,
+                costAllocationDomain: props.costAllocationDomain
+            });
+        }
         applyCostAllocationTags(this, {
             service: "hostedZone",
             domain: props.costAllocationDomain ?? props.zoneName,

package/package.json

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