@fjall/components-infrastructure 3.0.0 → 3.1.0

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,22 @@ 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.
+     */
+    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,13 @@ 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 AuditRoleFactory from "./resources/aws/audit/auditRole.js";
 import { FJALL_AUDIT_CONFIG } from "./config/audit.js";
 import { FjallLogger } from "./utils/validationLogger.js";
@@ -480,6 +482,36 @@ 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) {
+        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);
+        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/patterns/aws/buildkite/alarms.d.ts

@@ -0,0 +1,20 @@
+import type { Construct } from "constructs";
+export interface BuildkiteAlarmParams {
+    readonly buildkiteOrgSlug: string;
+    readonly buildkiteQueue: string;
+    readonly autoScalingGroupName: string;
+    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 { Topic } from "aws-cdk-lib/aws-sns";
+/**
+ * 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
+    });
+    if (params.alarmSnsTopicArn !== undefined) {
+        const topic = Topic.fromTopicArn(scope, "BuildkiteAlarmTopic", params.alarmSnsTopicArn);
+        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,233 @@
+import { CfnOutput, Duration, 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 { applyCostAllocationTags } from "../../../utils/costAllocationTags.js";
+import { addBuildkiteAlarms } from "./alarms.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`);
+        const managedSecretsBucket = new S3Bucket(this, `${id}ManagedSecretsBucket`);
+        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
+            })
+        });
+        addBuildkiteAlarms(this, {
+            buildkiteOrgSlug: config.buildkiteOrgSlug,
+            buildkiteQueue: config.buildkiteQueue,
+            autoScalingGroupName: autoScalingGroup.autoScalingGroupName,
+            ...(config.alarmSnsTopicArn !== undefined && {
+                alarmSnsTopicArn: config.alarmSnsTopicArn
+            })
+        });
+        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;