@fjall/components-infrastructure 3.0.0 → 3.1.0

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

@@ -0,0 +1,176 @@
+import { CompositePrincipal, PolicyDocument, PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
+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 const BUILDKITE_AGENT_IAM_ACTION_ALLOWLIST = [
+    "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"
+];
+/**
+ * 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 function buildAgentRole(scope, id, params) {
+    return new Role(scope, id, {
+        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"))
+    });
+}
+function buildAgentPolicyDocuments(params) {
+    const documents = {
+        readAgentSecrets: new PolicyDocument({
+            statements: [
+                new PolicyStatement({
+                    actions: ["ssm:GetParameter"],
+                    resources: [
+                        params.agentTokenParameterArn,
+                        ...(params.fjallApiKeyParameterArn !== undefined
+                            ? [params.fjallApiKeyParameterArn]
+                            : [])
+                    ]
+                }),
+                ...(params.agentTokenKmsKeyArn !== undefined
+                    ? [
+                        new PolicyStatement({
+                            actions: ["kms:Decrypt"],
+                            resources: [params.agentTokenKmsKeyArn]
+                        })
+                    ]
+                    : [])
+            ]
+        }),
+        readManagedSecretsBucket: new PolicyDocument({
+            statements: [
+                new PolicyStatement({
+                    actions: ["s3:GetObject", "s3:ListBucket"],
+                    resources: [params.secretsBucketArn, `${params.secretsBucketArn}/*`]
+                })
+            ]
+        }),
+        artifactBucket: new PolicyDocument({
+            statements: [
+                new PolicyStatement({
+                    // The Acl grants pair with the pinned BUILDKITE_S3_ACL env value:
+                    // S3 evaluates s3:PutObjectAcl whenever a PutObject request carries
+                    // an x-amz-acl header, so uploads fail AccessDenied without them.
+                    actions: [
+                        "s3:GetObject",
+                        "s3:GetObjectVersion",
+                        "s3:ListBucket",
+                        "s3:PutObject",
+                        "s3:PutObjectAcl",
+                        "s3:PutObjectVersionAcl"
+                    ],
+                    resources: [params.artifactBucketArn, `${params.artifactBucketArn}/*`]
+                })
+            ]
+        }),
+        logging: new PolicyDocument({
+            statements: [
+                new PolicyStatement({
+                    actions: [
+                        "logs:CreateLogGroup",
+                        "logs:CreateLogStream",
+                        "logs:PutLogEvents",
+                        "logs:PutRetentionPolicy"
+                    ],
+                    resources: [
+                        params.logGroupArnPattern,
+                        `${params.logGroupArnPattern}:*`
+                    ]
+                }),
+                new PolicyStatement({
+                    actions: ["logs:DescribeLogGroups", "logs:DescribeLogStreams"],
+                    resources: ["*"]
+                })
+            ]
+        }),
+        describeInstance: new PolicyDocument({
+            statements: [
+                new PolicyStatement({
+                    actions: [
+                        "autoscaling:DescribeAutoScalingInstances",
+                        "cloudwatch:PutMetricData",
+                        "ec2:DescribeTags"
+                    ],
+                    resources: ["*"]
+                }),
+                new PolicyStatement({
+                    actions: ["cloudformation:DescribeStackResource"],
+                    resources: [params.stackArn]
+                })
+            ]
+        }),
+        sessionManager: new PolicyDocument({
+            statements: [
+                new PolicyStatement({
+                    actions: [
+                        "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"
+                    ],
+                    resources: ["*"]
+                })
+            ]
+        })
+    };
+    return documents;
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Buildkite Elastic CI Stack version pins — the single moving-together
+ * contract for everything the `Buildkite` pattern derives from an upstream
+ * release. AMI ids, the elastic-stack version, the scaler version and the
+ * secrets-plugin floor MUST only change together, regenerated from the
+ * upstream template for the new version (runbook:
+ * `aiDocs/runbooks/buildkite-stack-bump-runbook.md`).
+ *
+ * AMI ids come from the `Mappings.AWSRegion2AMI` block of
+ * `https://s3.amazonaws.com/buildkite-aws-stack/<version>/aws-stack.yml` and
+ * are owner-verified against `ec2 describe-images` (owner MUST be
+ * `BUILDKITE_AMI_OWNER_ACCOUNT_ID`) before landing here. The vendored copy of
+ * the template lives at
+ * `lib/__tests__/fixtures/buildkite/upstream-aws-stack-<version>.yml` and
+ * backs the user-data parity test.
+ *
+ * Explicit ids rather than `MachineImage.lookup` — a name-pattern lookup
+ * floats the AMI underneath a pinned stack version, needs lookup credentials
+ * at synth time (unavailable in worker synth), and makes synth
+ * non-deterministic. Design:
+ * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md` § D2.
+ */
+export declare const BUILDKITE_AMI_OWNER_ACCOUNT_ID = "172840064832";
+export declare const BUILDKITE_CPU_ARCHITECTURES: readonly ["arm64", "amd64"];
+export type BuildkiteCpuArchitecture = (typeof BUILDKITE_CPU_ARCHITECTURES)[number];
+export declare const BUILDKITE_STACK_PINS: {
+    /** Upstream elastic-stack release the AMIs and user-data contract match. */
+    readonly elasticStackVersion: "v6.68.1";
+    /** buildkite-agent-scaler SAR semantic version. */
+    readonly scalerVersion: "1.12.0";
+    /**
+     * Minimum s3-secrets-hooks plugin version baked into the pinned AMIs.
+     * Versions bundled with elastic stack v6.41.0–6.41.3 leak secrets to the
+     * build log (GHSA fixed in 2.7.0); any bump below this floor must be
+     * rejected at review. v6.68.1 bundles >= 2.7.0.
+     */
+    readonly secretsPluginFloor: "2.7.0";
+    /**
+     * buildkite-agent-scaler SAR application ARNs per architecture, from the
+     * upstream template's `Mappings` block. The SAR publisher account is
+     * us-east-1-global; the ARN region does not constrain deploy region.
+     */
+    readonly scalerSarApplicationArns: {
+        readonly amd64: "arn:aws:serverlessrepo:us-east-1:172840064832:applications/buildkite-agent-scaler";
+        readonly arm64: "arn:aws:serverlessrepo:us-east-1:172840064832:applications/buildkite-agent-scaler-arm64";
+    };
+    /**
+     * Pinned AMI ids per region per architecture. Single-region today
+     * (us-east-1 — the fleet's home); add regions by regenerating from the
+     * upstream template, never by hand-picking an AMI. Owner-verified
+     * 2026-07-18: both ids owned by 172840064832, arm64 image
+     * `buildkite-stack-linux-arm64-2026-07-07T09-03-25Z`.
+     */
+    readonly amiIdsByRegion: {
+        readonly "us-east-1": {
+            readonly arm64: "ami-0ca21e2db030163c8";
+            readonly amd64: "ami-0a28a471ffade73ed";
+        };
+    };
+};
+export type BuildkiteSupportedRegion = keyof typeof BUILDKITE_STACK_PINS.amiIdsByRegion;
+/**
+ * Resolve the pinned AMI id for a concrete region + architecture. Throws a
+ * synth-time error with the remediation path when the region is not pinned —
+ * adding a region is a pins regeneration, not a call-site workaround.
+ */
+export declare function resolvePinnedAmiId(region: string, architecture: BuildkiteCpuArchitecture): string;
+/** Resolve the architecture-matched buildkite-agent-scaler SAR ARN. */
+export declare function resolveScalerSarApplicationArn(architecture: BuildkiteCpuArchitecture): string;

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

@@ -0,0 +1,80 @@
+/**
+ * Buildkite Elastic CI Stack version pins — the single moving-together
+ * contract for everything the `Buildkite` pattern derives from an upstream
+ * release. AMI ids, the elastic-stack version, the scaler version and the
+ * secrets-plugin floor MUST only change together, regenerated from the
+ * upstream template for the new version (runbook:
+ * `aiDocs/runbooks/buildkite-stack-bump-runbook.md`).
+ *
+ * AMI ids come from the `Mappings.AWSRegion2AMI` block of
+ * `https://s3.amazonaws.com/buildkite-aws-stack/<version>/aws-stack.yml` and
+ * are owner-verified against `ec2 describe-images` (owner MUST be
+ * `BUILDKITE_AMI_OWNER_ACCOUNT_ID`) before landing here. The vendored copy of
+ * the template lives at
+ * `lib/__tests__/fixtures/buildkite/upstream-aws-stack-<version>.yml` and
+ * backs the user-data parity test.
+ *
+ * Explicit ids rather than `MachineImage.lookup` — a name-pattern lookup
+ * floats the AMI underneath a pinned stack version, needs lookup credentials
+ * at synth time (unavailable in worker synth), and makes synth
+ * non-deterministic. Design:
+ * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md` § D2.
+ */
+export const BUILDKITE_AMI_OWNER_ACCOUNT_ID = "172840064832";
+export const BUILDKITE_CPU_ARCHITECTURES = ["arm64", "amd64"];
+export const BUILDKITE_STACK_PINS = {
+    /** Upstream elastic-stack release the AMIs and user-data contract match. */
+    elasticStackVersion: "v6.68.1",
+    /** buildkite-agent-scaler SAR semantic version. */
+    scalerVersion: "1.12.0",
+    /**
+     * Minimum s3-secrets-hooks plugin version baked into the pinned AMIs.
+     * Versions bundled with elastic stack v6.41.0–6.41.3 leak secrets to the
+     * build log (GHSA fixed in 2.7.0); any bump below this floor must be
+     * rejected at review. v6.68.1 bundles >= 2.7.0.
+     */
+    secretsPluginFloor: "2.7.0",
+    /**
+     * buildkite-agent-scaler SAR application ARNs per architecture, from the
+     * upstream template's `Mappings` block. The SAR publisher account is
+     * us-east-1-global; the ARN region does not constrain deploy region.
+     */
+    scalerSarApplicationArns: {
+        amd64: "arn:aws:serverlessrepo:us-east-1:172840064832:applications/buildkite-agent-scaler",
+        arm64: "arn:aws:serverlessrepo:us-east-1:172840064832:applications/buildkite-agent-scaler-arm64"
+    },
+    /**
+     * Pinned AMI ids per region per architecture. Single-region today
+     * (us-east-1 — the fleet's home); add regions by regenerating from the
+     * upstream template, never by hand-picking an AMI. Owner-verified
+     * 2026-07-18: both ids owned by 172840064832, arm64 image
+     * `buildkite-stack-linux-arm64-2026-07-07T09-03-25Z`.
+     */
+    amiIdsByRegion: {
+        "us-east-1": {
+            arm64: "ami-0ca21e2db030163c8",
+            amd64: "ami-0a28a471ffade73ed"
+        }
+    }
+};
+function isSupportedRegion(region) {
+    return region in BUILDKITE_STACK_PINS.amiIdsByRegion;
+}
+/**
+ * Resolve the pinned AMI id for a concrete region + architecture. Throws a
+ * synth-time error with the remediation path when the region is not pinned —
+ * adding a region is a pins regeneration, not a call-site workaround.
+ */
+export function resolvePinnedAmiId(region, architecture) {
+    if (!isSupportedRegion(region)) {
+        throw new Error(`Buildkite: no pinned AMI for region '${region}'. Supported: ` +
+            `${Object.keys(BUILDKITE_STACK_PINS.amiIdsByRegion).join(", ")}. ` +
+            `Add the region to BUILDKITE_STACK_PINS via the bump runbook ` +
+            `(aiDocs/runbooks/buildkite-stack-bump-runbook.md).`);
+    }
+    return BUILDKITE_STACK_PINS.amiIdsByRegion[region][architecture];
+}
+/** Resolve the architecture-matched buildkite-agent-scaler SAR ARN. */
+export function resolveScalerSarApplicationArn(architecture) {
+    return BUILDKITE_STACK_PINS.scalerSarApplicationArns[architecture];
+}

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

@@ -0,0 +1,80 @@
+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).
+ */
+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;

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

@@ -0,0 +1,148 @@
+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).
+ */
+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;
+}

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

@@ -0,0 +1,58 @@
+import { MultipartUserData } from "aws-cdk-lib/aws-ec2";
+import type { BuildkiteProps } from "./schema.js";
+/**
+ * Resolved synth-time values the user data needs beyond the plain props —
+ * supplied by the construct (region from `Stack.of(this)`, never
+ * `props.env?.region`, which rendered the literal string "undefined" in the
+ * pre-refactor stack).
+ */
+export interface BuildkiteUserDataContext {
+    readonly stackName: string;
+    readonly region: string;
+    readonly secretsBucketName: string;
+    readonly artifactBucketName: string;
+}
+/**
+ * The pinned AMI's boot scripts run under `set -Eeuo pipefail` and
+ * dereference every variable the upstream template passes — an OMITTED key
+ * is not "use the default", it is an unbound-variable crash at boot and an
+ * ASG boot-loop. Each part therefore mirrors the upstream v6.68.1 user data
+ * env block EXACTLY (same keys, upstream parameter defaults where we expose
+ * no knob), and the parity test asserts set equality per part against the
+ * vendored template in both directions: a key we emit that upstream does not
+ * pass is silently ignored; a key upstream passes that we omit is the
+ * boot-loop. Bumping the pins regenerates the fixture
+ * (runbook: `aiDocs/runbooks/buildkite-stack-bump-runbook.md`).
+ */
+export declare const BUILDKITE_MOUNT_PART_ENV_KEYS: readonly ["BUILDKITE_ENABLE_INSTANCE_STORAGE", "BUILDKITE_MOUNT_TMPFS_AT_TMP"];
+export declare const BUILDKITE_DOCKER_PART_ENV_KEYS: readonly ["DOCKER_USERNS_REMAP", "DOCKER_EXPERIMENTAL", "DOCKER_PRUNE_UNTIL", "ENABLE_PRE_EXIT_DISK_CLEANUP", "DOCKER_BUILDER_PRUNE_ENABLED", "DOCKER_NETWORKING_PROTOCOL", "DOCKER_IPV4_ADDRESS_POOL_1", "DOCKER_IPV4_ADDRESS_POOL_2", "DOCKER_IPV6_ADDRESS_POOL", "DOCKER_FIXED_CIDR_V4", "DOCKER_FIXED_CIDR_V6", "BUILDKITE_ENABLE_INSTANCE_STORAGE"];
+export declare const BUILDKITE_USER_DATA_ENV_KEYS: readonly ["BUILDKITE_STACK_NAME", "BUILDKITE_STACK_VERSION", "BUILDKITE_STACK_DEPLOYED_BY", "BUILDKITE_SCALE_IN_IDLE_PERIOD", "BUILDKITE_SECRETS_BUCKET", "BUILDKITE_SECRETS_BUCKET_REGION", "BUILDKITE_SECRETS_PLUGIN_SKIP_SSH_KEY_NOT_FOUND_WARNING", "BUILDKITE_ARTIFACTS_BUCKET", "BUILDKITE_S3_DEFAULT_REGION", "BUILDKITE_S3_ACL", "BUILDKITE_AGENT_TOKEN_PATH", "BUILDKITE_AGENTS_PER_INSTANCE", "BUILDKITE_AGENT_ENDPOINT", "BUILDKITE_AGENT_TAGS", "BUILDKITE_AGENT_TIMESTAMP_LINES", "BUILDKITE_AGENT_EXPERIMENTS", "BUILDKITE_AGENT_TRACING_BACKEND", "BUILDKITE_AGENT_SIGNING_KEY_PATH", "BUILDKITE_AGENT_SIGNING_KEY_ID", "BUILDKITE_AGENT_VERIFICATION_KEY_PATH", "BUILDKITE_AGENT_RELEASE", "BUILDKITE_AGENT_CANCEL_GRACE_PERIOD", "BUILDKITE_AGENT_SIGNAL_GRACE_PERIOD_SECONDS", "BUILDKITE_AGENT_SIGNING_KMS_KEY", "BUILDKITE_AGENT_JOB_VERIFICATION_NO_SIGNATURE_BEHAVIOR", "BUILDKITE_QUEUE", "BUILDKITE_AGENT_ENABLE_GIT_MIRRORS", "BUILDKITE_ELASTIC_BOOTSTRAP_SCRIPT", "BUILDKITE_ENV_FILE_URL", "BUILDKITE_ENABLE_INSTANCE_STORAGE", "BUILDKITE_AUTHORIZED_USERS_URL", "BUILDKITE_ECR_POLICY", "BUILDKITE_TERMINATE_INSTANCE_AFTER_JOB", "BUILDKITE_AGENT_DISCONNECT_AFTER_UPTIME", "BUILDKITE_TERMINATE_INSTANCE_ON_DISK_FULL", "BUILDKITE_PURGE_BUILDS_ON_DISK_FULL", "BUILDKITE_ADDITIONAL_SUDO_PERMISSIONS", "AWS_DEFAULT_REGION", "SECRETS_PLUGIN_ENABLED", "ECR_PLUGIN_ENABLED", "ECR_CREDENTIAL_HELPER_ENABLED", "DOCKER_LOGIN_PLUGIN_ENABLED", "DOCKER_EXPERIMENTAL", "DOCKER_PRUNE_UNTIL", "ENABLE_PRE_EXIT_DISK_CLEANUP", "DOCKER_BUILDER_PRUNE_ENABLED", "DOCKER_USERNS_REMAP", "AWS_REGION", "ENABLE_RESOURCE_LIMITS", "RESOURCE_LIMITS_MEMORY_HIGH", "RESOURCE_LIMITS_MEMORY_MAX", "RESOURCE_LIMITS_MEMORY_SWAP_MAX", "RESOURCE_LIMITS_CPU_WEIGHT", "RESOURCE_LIMITS_CPU_QUOTA", "RESOURCE_LIMITS_IO_WEIGHT", "ENABLE_EC2_LOG_RETENTION_POLICY", "EC2_LOG_RETENTION_DAYS"];
+/**
+ * Build the agent instance's multipart user data against the pinned elastic
+ * stack's boot scripts (cloud-config re-run marker, storage mount, docker
+ * config, `bk-install-elastic-stack.sh`).
+ */
+export declare function buildBuildkiteUserData(props: BuildkiteProps, context: BuildkiteUserDataContext): MultipartUserData;
+/** Storage-mount part — `bk-mount-instance-storage.sh` env assignments. */
+export declare function buildBuildkiteMountCommands(props: BuildkiteProps): string[];
+/** Docker-configure part — `bk-configure-docker.sh` env assignments. */
+export declare function buildBuildkiteDockerCommands(props: BuildkiteProps): string[];
+/**
+ * Install part — the env assignments handed to the pinned
+ * `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:
+ *
+ * - `BUILDKITE_S3_ACL`: our artifact bucket is BucketOwnerEnforced (ACLs
+ *   disabled), where S3 rejects every canned ACL EXCEPT
+ *   `bucket-owner-full-control` — upstream's `private` default would fail
+ *   every artifact upload with AccessControlListNotSupported.
+ * - `BUILDKITE_ECR_POLICY`: hard-pinned `none` (design § D9 — the instance
+ *   profile confers no registry credentials).
+ * - `BUILDKITE_AGENT_SIGNING_KMS_KEY`: hard-pinned empty. Pipeline signing
+ *   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).
+ */
+export declare function buildBuildkiteInstallCommands(props: BuildkiteProps, context: BuildkiteUserDataContext): string[];