@fjall/components-infrastructure 3.0.0 → 3.2.1

package/dist/lib/app.d.ts

@@ -16,6 +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 { 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";
@@ -277,6 +278,29 @@ export declare class App extends CdkApp {
      * would synth and hash but never deploy.
      */
     addDevSubstrate(props: IDevSubstrateProps): DevSubstrate;
+    /**
+     * 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.
+     *
+     * Alarm actions default to the account's `SharedAlarmTopicArn` export
+     * (design § D14 — alerting ships WITH the fleet): every fjall-governed
+     * account's Account/Platform stack produces that export, so alarms page
+     * out of the box. An explicit `props.alarmSnsTopicArn` still wins.
+     * `applicationId` defaults to the app name so the alarm webhook can map
+     * pages to the application; an explicit prop still wins.
+     */
+    addBuildkite(props: BuildkitePropsInput): 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,11 +9,14 @@ 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 { 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 { SHARED_ALARM_TOPIC_EXPORT_NAME } from "./config/aws/alarmTopic.js";
 import AuditRoleFactory from "./resources/aws/audit/auditRole.js";
 import { FJALL_AUDIT_CONFIG } from "./config/audit.js";
 import { FjallLogger } from "./utils/validationLogger.js";
@@ -480,6 +483,49 @@ 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.
+     *
+     * Alarm actions default to the account's `SharedAlarmTopicArn` export
+     * (design § D14 — alerting ships WITH the fleet): every fjall-governed
+     * account's Account/Platform stack produces that export, so alarms page
+     * out of the box. An explicit `props.alarmSnsTopicArn` still wins.
+     * `applicationId` defaults to the app name so the alarm webhook can map
+     * pages to the application; an explicit prop still wins.
+     */
+    addBuildkite(props) {
+        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;
+        }
+        if (constructProps.alarmSnsTopicArn === undefined) {
+            constructProps.alarmSnsTopicArn = `import:${SHARED_ALARM_TOPIC_EXPORT_NAME}`;
+        }
+        if (constructProps.applicationId === undefined) {
+            constructProps.applicationId = this.getName();
+        }
+        const fleet = new Buildkite(computeStack.getStack(), "Buildkite", constructProps);
+        computeStack.addConstruct(fleet);
+        return fleet;
+    }
     /**
      * 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/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/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

@@ -0,0 +1,25 @@
+import type { Construct } from "constructs";
+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;
+}
+/**
+ * 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 addBuildkiteAlarms(scope: Construct, params: BuildkiteAlarmParams): void;

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

@@ -0,0 +1,78 @@
+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 { 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
+ * 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 addBuildkiteAlarms(scope, params) {
+    const scheduledJobs = new Metric({
+        namespace: SCALER_METRICS_NAMESPACE,
+        metricName: "ScheduledJobsCount",
+        dimensionsMap: {
+            Org: params.buildkiteOrgSlug,
+            Queue: params.buildkiteQueue
+        },
+        statistic: "Maximum",
+        period: Duration.minutes(5)
+    });
+    const heartbeatAlarm = new Alarm(scope, "ScalerHeartbeatAlarm", {
+        alarmDescription: `Buildkite scaler for queue '${params.buildkiteQueue}' has stopped ` +
+            "publishing metrics — scaler Lambda dead or erroring. Jobs will queue " +
+            "with no scale-out.",
+        metric: scheduledJobs,
+        comparisonOperator: ComparisonOperator.LESS_THAN_THRESHOLD,
+        threshold: 0,
+        evaluationPeriods: 3,
+        treatMissingData: TreatMissingData.BREACHING
+    });
+    const inServiceInstances = new Metric({
+        namespace: "AWS/AutoScaling",
+        metricName: "GroupInServiceInstances",
+        dimensionsMap: { AutoScalingGroupName: params.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: `Buildkite queue '${params.buildkiteQueue}' has scheduled jobs but ` +
+            "zero in-service agents for 15 minutes — the fleet cannot boot " +
+            "(AMI, quota, or subnet failure) while work waits.",
+        metric: queuedWithZeroCapacity,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+        threshold: 1,
+        evaluationPeriods: 3,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    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.d.ts

@@ -0,0 +1,46 @@
+import { type IVpc } from "aws-cdk-lib/aws-ec2";
+import { Construct } from "constructs";
+import { type BuildkitePropsInput } from "./schema.js";
+export type BuildkiteConstructProps = BuildkitePropsInput & {
+    readonly vpc: IVpc;
+};
+/**
+ * Self-hosted Buildkite agent fleet on the pinned Elastic CI Stack AMIs —
+ * scale-to-zero ASG + buildkite-agent-scaler, no secret ever transiting
+ * synth, allowlist-only instance IAM. Design:
+ * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`.
+ *
+ * A Construct, not a Stack: instantiate via `App.addBuildkite(props)`, which
+ * scopes it under the default compute stack so deploy-core's fixed
+ * six-category stack selection actually deploys it (the DevSubstrate
+ * placement precedent). Network posture is public-subnet + public-IP +
+ * zero-ingress (design § D5): `associatePublicIpAddress` MUST be explicit —
+ * the wrapper's `!!keyPair` default silently produced no-egress agents in
+ * public subnets pre-refactor.
+ */
+export declare class Buildkite extends Construct {
+    readonly artifactBucketName: string;
+    readonly secretsBucketName: string;
+    readonly autoScalingGroupName: string;
+    constructor(scope: Construct, id: string, props: BuildkiteConstructProps);
+    /**
+     * Ship the per-job `env` hook into the managed secrets bucket. The
+     * s3-secrets-hooks plugin sources this file at the start of EVERY job, so
+     * FJALL_API_KEY is read fresh from SSM per job — rotation takes effect on
+     * the next job with no instance replacement (design § D4(iii)). The script
+     * is configuration, not a secret: shipping it through a CDK asset is fine;
+     * the secret VALUE only ever moves SSM → instance at job runtime.
+     */
+    private addFjallApiKeyEnvHook;
+}
+/**
+ * Object key the s3-secrets-hooks plugin sources at the start of every job —
+ * upstream contract: `env` at the secrets-bucket root.
+ */
+export declare const FJALL_ENV_HOOK_OBJECT_KEY = "env";
+/**
+ * The per-job env hook's script content (design § D4(iii)): FJALL_API_KEY is
+ * read fresh from SSM per job, so rotation takes effect on the next job with
+ * no instance replacement. Pure — the unit test pins the exact content.
+ */
+export declare function buildFjallApiKeyEnvHookScript(parameterName: string, region: string): string;

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

@@ -0,0 +1,240 @@
+import { CfnOutput, Duration, RemovalPolicy, Stack, Token } from "aws-cdk-lib";
+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";
+import { Construct } from "constructs";
+import { safeEbs } from "../../../resources/aws/compute/blockDeviceVolume.js";
+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 { resolveAlertsTopic } from "../../../utils/resolveAlertsTopic.js";
+import { buildAgentRole } from "./iam.js";
+import { BUILDKITE_STACK_PINS, resolvePinnedAmiId, resolveScalerSarApplicationArn } from "./pins.js";
+import { validateBuildkiteProps } from "./schema.js";
+import { buildBuildkiteUserData } from "./userData.js";
+/**
+ * Self-hosted Buildkite agent fleet on the pinned Elastic CI Stack AMIs —
+ * scale-to-zero ASG + buildkite-agent-scaler, no secret ever transiting
+ * synth, allowlist-only instance IAM. Design:
+ * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`.
+ *
+ * A Construct, not a Stack: instantiate via `App.addBuildkite(props)`, which
+ * scopes it under the default compute stack so deploy-core's fixed
+ * six-category stack selection actually deploys it (the DevSubstrate
+ * placement precedent). Network posture is public-subnet + public-IP +
+ * zero-ingress (design § D5): `associatePublicIpAddress` MUST be explicit —
+ * the wrapper's `!!keyPair` default silently produced no-egress agents in
+ * public subnets pre-refactor.
+ */
+export class Buildkite extends Construct {
+    artifactBucketName;
+    secretsBucketName;
+    autoScalingGroupName;
+    constructor(scope, id, props) {
+        super(scope, id);
+        const { vpc, ...plainProps } = props;
+        const config = validateBuildkiteProps(plainProps);
+        const stack = Stack.of(this);
+        if (Token.isUnresolved(stack.region)) {
+            throw new Error("Buildkite requires a concrete env region at synth (the pinned AMI " +
+                "is region-specific). Pass env: { account, region } to the App.");
+        }
+        const region = stack.region;
+        const architecture = deriveCpuArchitecture(config.instanceType);
+        const amiId = resolvePinnedAmiId(region, architecture);
+        applyCostAllocationTags(this, {
+            service: "buildkite",
+            domain: "platform",
+            ...(config.costAllocationEnvironment !== undefined && {
+                environment: config.costAllocationEnvironment
+            }),
+            ...(config.costAllocationOwner !== undefined && {
+                owner: config.costAllocationOwner
+            })
+        });
+        const artifactBucket = new S3Bucket(this, `${id}ArtifactBucket`);
+        // 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);
+        }
+        const parameterArn = (name) => `arn:${stack.partition}:ssm:${region}:${stack.account}:parameter${name}`;
+        const agentRole = buildAgentRole(this, `${id}AgentRole`, {
+            agentTokenParameterArn: parameterArn(config.agentTokenSsmParameterName),
+            ...(config.agentTokenKmsKeyArn !== undefined && {
+                agentTokenKmsKeyArn: config.agentTokenKmsKeyArn
+            }),
+            ...(config.fjallApiKeySsmParameterName !== undefined && {
+                fjallApiKeyParameterArn: parameterArn(config.fjallApiKeySsmParameterName)
+            }),
+            secretsBucketArn: managedSecretsBucket.bucketArn,
+            artifactBucketArn: artifactBucket.bucketArn,
+            stackArn: stack.stackId,
+            logGroupArnPattern: `arn:${stack.partition}:logs:${region}:${stack.account}:log-group:/buildkite/*`
+        });
+        const userData = buildBuildkiteUserData(config, {
+            stackName: stack.stackName,
+            region,
+            secretsBucketName: managedSecretsBucket.bucketName,
+            artifactBucketName: artifactBucket.bucketName
+        });
+        // Deliberate deviation from upstream's InstanceScaleInProtection
+        // (design § D7): the wrapper's `newInstancesProtectedFromScaleIn: false`
+        // invariant wins (scale-in-protected instances wedge CFN rollback). Safe
+        // because the scaler runs with `DisableScaleIn: "true"` (pinned below) so
+        // it never reduces DesiredCapacity — instances leave only by
+        // self-termination (scale-in idle / disconnect-after-uptime) or the ASG
+        // `maxInstanceLifetime` replacement.
+        //
+        // `ssmSessionPermissions: false`: the wrapper default attaches
+        // `AmazonSSMManagedInstanceCore`, whose account-wide `ssm:GetParameter`
+        // would let any build job read every SSM parameter in the account —
+        // breaking § D9's allowlist-only posture. The agent role's scoped
+        // `sessionManager` inline policy carries the Session Manager actions.
+        const ec2Instance = new Ec2Instance(this, `${id}Agent`, {
+            serviceName: `${id}Agent`,
+            vpc,
+            vpcSubnets: { subnetType: SubnetType.PUBLIC },
+            associatePublicIpAddress: true,
+            instanceType: config.instanceType,
+            machineImage: MachineImage.genericLinux({ [region]: amiId }),
+            userData,
+            role: agentRole,
+            ssmSessionPermissions: false,
+            blockDevices: [
+                {
+                    deviceName: "/dev/xvda",
+                    volume: safeEbs(config.agentVolumeSizeGib)
+                }
+            ],
+            minCapacity: config.agentMinInstances,
+            maxCapacity: config.agentMaxInstances,
+            spotCapacityPercentage: config.spotCapacityPercentage,
+            maxInstanceLifetime: Duration.days(config.maxInstanceLifetimeDays),
+            tags: {
+                Role: "buildkite-agent",
+                BuildkiteQueue: config.buildkiteQueue,
+                BuildkiteAgentRelease: config.buildkiteAgentRelease,
+                AgentsPerInstance: `${config.agentsPerInstance}`
+            }
+        });
+        const autoScalingGroup = ec2Instance.getAutoScalingGroup();
+        agentRole.attachInlinePolicy(new Policy(this, `${id}AgentScaleInPolicy`, {
+            statements: [
+                new PolicyStatement({
+                    actions: [
+                        "autoscaling:SetInstanceHealth",
+                        "autoscaling:TerminateInstanceInAutoScalingGroup"
+                    ],
+                    resources: [autoScalingGroup.autoScalingGroupArn]
+                })
+            ]
+        }));
+        new SamApplication(this, `${id}AgentScaler`, {
+            applicationId: resolveScalerSarApplicationArn(architecture),
+            semanticVersion: BUILDKITE_STACK_PINS.scalerVersion,
+            parameters: {
+                BuildkiteAgentTokenParameter: config.agentTokenSsmParameterName,
+                ...(config.agentTokenKmsKeyArn !== undefined && {
+                    BuildkiteAgentTokenParameterStoreKMSKey: config.agentTokenKmsKeyArn
+                }),
+                ...(config.rolePermissionsBoundaryArn !== undefined && {
+                    RolePermissionsBoundaryARN: config.rolePermissionsBoundaryArn
+                }),
+                BuildkiteQueue: config.buildkiteQueue,
+                AgentsPerInstance: `${config.agentsPerInstance}`,
+                MinSize: `${config.agentMinInstances}`,
+                MaxSize: `${config.agentMaxInstances}`,
+                AgentAutoScaleGroup: autoScalingGroup.autoScalingGroupName,
+                ScaleOutFactor: config.scaleOutFactor,
+                ScaleOutForWaitingJobs: `${config.scaleOutWaitingForJobs}`,
+                EventSchedulePeriod: config.scalerEventSchedulePeriod,
+                MinPollInterval: config.scalerMinPollInterval,
+                LogRetentionDays: `${config.logRetentionDays}`,
+                // Pinned, not defaulted: the D7 scale-in posture above is only sound
+                // while the scaler never reduces DesiredCapacity. A scaler-side
+                // default flip must not change our termination semantics silently.
+                DisableScaleIn: "true"
+            },
+            costAllocationService: "buildkite",
+            costAllocationDomain: "buildkite-agent-scaler",
+            ...(config.costAllocationEnvironment !== undefined && {
+                costAllocationEnvironment: config.costAllocationEnvironment
+            })
+        });
+        const alertsTopic = resolveAlertsTopic(this, "BuildkiteAlarmTopic", config.alarmSnsTopicArn);
+        createBuildkiteAlarms({
+            scope: this,
+            buildkiteOrgSlug: config.buildkiteOrgSlug,
+            buildkiteQueue: config.buildkiteQueue,
+            autoScalingGroupName: autoScalingGroup.autoScalingGroupName,
+            ...(alertsTopic !== undefined && { alarmTopic: alertsTopic }),
+            ...(config.applicationId !== undefined && {
+                applicationId: config.applicationId
+            })
+        });
+        this.artifactBucketName = artifactBucket.bucketName;
+        this.secretsBucketName = managedSecretsBucket.bucketName;
+        this.autoScalingGroupName = autoScalingGroup.autoScalingGroupName;
+        new CfnOutput(this, "BuildkiteQueueName", {
+            value: config.buildkiteQueue
+        });
+        new CfnOutput(this, "BuildkiteAgentAsgName", {
+            value: autoScalingGroup.autoScalingGroupName
+        });
+        new CfnOutput(this, "BuildkiteSecretsBucketName", {
+            value: managedSecretsBucket.bucketName
+        });
+        new CfnOutput(this, "BuildkiteArtifactBucketName", {
+            value: artifactBucket.bucketName
+        });
+    }
+    /**
+     * Ship the per-job `env` hook into the managed secrets bucket. The
+     * s3-secrets-hooks plugin sources this file at the start of EVERY job, so
+     * FJALL_API_KEY is read fresh from SSM per job — rotation takes effect on
+     * the next job with no instance replacement (design § D4(iii)). The script
+     * is configuration, not a secret: shipping it through a CDK asset is fine;
+     * the secret VALUE only ever moves SSM → instance at job runtime.
+     */
+    addFjallApiKeyEnvHook(id, secretsBucket, parameterName, region) {
+        new BucketDeployment(this, `${id}EnvHookDeployment`, {
+            sources: [
+                Source.data(FJALL_ENV_HOOK_OBJECT_KEY, buildFjallApiKeyEnvHookScript(parameterName, region))
+            ],
+            destinationBucket: secretsBucket,
+            // The secrets bucket also holds out-of-band objects the deployment
+            // does not know about (the git deploy key, design § D4(ii)). The CDK
+            // default `prune: true` DELETES every bucket object missing from
+            // `sources` on each custom-resource execution — wiping those secrets.
+            prune: false,
+            retainOnDelete: true
+        });
+    }
+}
+/**
+ * Object key the s3-secrets-hooks plugin sources at the start of every job —
+ * upstream contract: `env` at the secrets-bucket root.
+ */
+export const FJALL_ENV_HOOK_OBJECT_KEY = "env";
+/**
+ * The per-job env hook's script content (design § D4(iii)): FJALL_API_KEY is
+ * read fresh from SSM per job, so rotation takes effect on the next job with
+ * no instance replacement. Pure — the unit test pins the exact content.
+ */
+export function buildFjallApiKeyEnvHookScript(parameterName, region) {
+    return [
+        `FJALL_API_KEY="$(aws ssm get-parameter --name '${parameterName}' --with-decryption --query Parameter.Value --output text --region '${region}')"`,
+        "export FJALL_API_KEY",
+        ""
+    ].join("\n");
+}
+function deriveCpuArchitecture(instanceTypeIdentifier) {
+    const architecture = new InstanceType(instanceTypeIdentifier).architecture;
+    return architecture === InstanceArchitecture.ARM_64 ? "arm64" : "amd64";
+}

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

@@ -0,0 +1,35 @@
+import type { Construct } from "constructs";
+import { Role } from "../../../resources/aws/iam/index.js";
+/**
+ * Every IAM action the agent instance profile is permitted to carry — the
+ * no-deploy-IAM invariant (design § D9). Deploy AWS credentials are
+ * server-minted (FJALL_API_KEY → Fjall OIDC → target-account role); the
+ * instance profile confers NO deploy capability. Explicitly absent: any
+ * `ecr:*` write, `sts:AssumeRole`, any CloudFormation mutation.
+ *
+ * The allowlist synth test asserts the synthesised role's actions are a
+ * subset of this list, so an upstream bump (or a future edit) that grows
+ * permissions fails loudly instead of shipping silently.
+ */
+export declare const BUILDKITE_AGENT_IAM_ACTION_ALLOWLIST: readonly ["ssm:GetParameter", "kms:Decrypt", "s3:GetObject", "s3:ListBucket", "s3:GetObjectVersion", "s3:PutObject", "s3:PutObjectAcl", "s3:PutObjectVersionAcl", "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogGroups", "logs:DescribeLogStreams", "logs:PutRetentionPolicy", "ssm:DescribeInstanceProperties", "ssm:ListAssociations", "ssm:PutInventory", "ssm:UpdateInstanceInformation", "ssmmessages:CreateControlChannel", "ssmmessages:CreateDataChannel", "ssmmessages:OpenControlChannel", "ssmmessages:OpenDataChannel", "ec2messages:AcknowledgeMessage", "ec2messages:DeleteMessage", "ec2messages:FailMessage", "ec2messages:GetEndpoint", "ec2messages:GetMessages", "ec2messages:SendReply", "autoscaling:DescribeAutoScalingInstances", "autoscaling:SetInstanceHealth", "autoscaling:TerminateInstanceInAutoScalingGroup", "cloudwatch:PutMetricData", "cloudformation:DescribeStackResource", "ec2:DescribeTags"];
+export interface BuildkiteAgentRoleParams {
+    readonly agentTokenParameterArn: string;
+    readonly agentTokenKmsKeyArn?: string;
+    readonly fjallApiKeyParameterArn?: string;
+    readonly secretsBucketArn: string;
+    readonly artifactBucketArn: string;
+    /** Own-stack ARN — `cloudformation:DescribeStackResource` scope. */
+    readonly stackArn: string;
+    /** `arn:...:log-group:/buildkite/*` — the elastic stack's group namespace. */
+    readonly logGroupArnPattern: string;
+}
+/**
+ * Build the agent instance role. Tighter than the upstream v6.68.1 template
+ * on three axes: logs actions are scoped to the `/buildkite/*` group
+ * namespace (upstream: `*`), `cloudformation:DescribeStackResource` is
+ * scoped to the own stack (upstream: `*`), and there is no ECR/docker-login
+ * grant surface at all. The remaining `resources: ["*"]` statements are
+ * describe-only or instance-inventory actions with no resource-level
+ * support.
+ */
+export declare function buildAgentRole(scope: Construct, id: string, params: BuildkiteAgentRoleParams): Role;