@fjall/components-infrastructure 4.4.0 → 6.0.0

package/dist/lib/resources/aws/compute/ecsCapacityConfig.js

@@ -0,0 +1,161 @@
+import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
+import { Token } from "aws-cdk-lib";
+import { DEFAULT_EC2_INSTANCE_TYPE, DEFAULT_EC2_MIN_CAPACITY, DEFAULT_EC2_MAX_CAPACITY, DEFAULT_EC2_INSTANCE_MONITORING, DEFAULT_WARM_POOL_MIN_SIZE, DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN, inferAmiHardwareType } from "./ecsConstants.js";
+/**
+ * Every `Ec2CapacityConfig` field, classified. The `Record<keyof …, …>`
+ * satisfies-shape is a compile-time exhaustiveness guard in compiled `src/`
+ * (typescript-standards § "Compile-time guards must live in compiled src/"):
+ * adding a field to `Ec2CapacityConfig` without classifying it here fails
+ * `tsc`, so a new ASG-shaping field cannot silently join the "not compared,
+ * silently discarded on a shared ASG" bucket.
+ */
+const EC2_CONFIG_FIELD_ROLES = {
+    instanceType: "keyed",
+    amiHardwareType: "keyed",
+    warmPool: "keyed",
+    persistentDataVolume: "keyed",
+    availabilityZones: "keyed",
+    minCapacity: "scalar",
+    maxCapacity: "scalar",
+    desiredCapacity: "scalar",
+    instanceMonitoring: "scalar",
+    associatePublicIpAddress: "scalar",
+    machineImage: "opaque",
+    userData: "opaque",
+    blockDevices: "opaque",
+    tags: "tags",
+    memoryLimitMiB: "taskDefinition"
+};
+function fieldsWithRole(role) {
+    return Object.keys(EC2_CONFIG_FIELD_ROLES).filter((field) => EC2_CONFIG_FIELD_ROLES[field] === role);
+}
+const KEYED_ASG_FIELDS = fieldsWithRole("keyed");
+const SCALAR_ASG_FIELDS = fieldsWithRole("scalar");
+const OPAQUE_ASG_FIELDS = fieldsWithRole("opaque");
+/**
+ * Defaults resolved before a scalar field is compared — the SAME values the
+ * ASG construction applies (`getOrCreateAsgCapacityProvider`), imported from
+ * their `ecsConstants.ts` single source, so an explicit value equal to the
+ * default compares equal to an omitted one instead of tripping the drift
+ * throw on a pair that synthesises identically. Fields with no construction
+ * default (`desiredCapacity`, `associatePublicIpAddress`) compare raw.
+ */
+const SCALAR_ASG_FIELD_DEFAULTS = {
+    minCapacity: DEFAULT_EC2_MIN_CAPACITY,
+    maxCapacity: DEFAULT_EC2_MAX_CAPACITY,
+    instanceMonitoring: DEFAULT_EC2_INSTANCE_MONITORING
+};
+function resolvedScalar(config, field) {
+    return config[field] ?? SCALAR_ASG_FIELD_DEFAULTS[field];
+}
+/** Deep tag-record equality, treating `{}` and absent as the same ASG shape. */
+function tagRecordsEqual(a, b) {
+    const aKeys = a === undefined ? [] : Object.keys(a);
+    const bKeys = b === undefined ? [] : Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    if (a === undefined || b === undefined)
+        return true;
+    return aKeys.every((key) => Object.is(a[key], b[key]));
+}
+function findDifferingAsgFields(ec2Config, origin) {
+    const differing = SCALAR_ASG_FIELDS.filter((field) => !Object.is(resolvedScalar(ec2Config, field), resolvedScalar(origin, field)));
+    if (!tagRecordsEqual(ec2Config.tags, origin.tags))
+        differing.push("tags");
+    for (const field of OPAQUE_ASG_FIELDS) {
+        if ((ec2Config[field] === undefined) !== (origin[field] === undefined)) {
+            differing.push(field);
+        }
+    }
+    return differing;
+}
+/**
+ * Rejects at synth when a service reusing a shared ASG is incompatible with
+ * it: either the origin's `persistentDataVolume` makes the ASG a singleton
+ * (two tasks would race to attach the same EBS volume), or the reusing
+ * service asks for ASG settings that differ from the ones the ASG was built
+ * with — those settings would be silently ignored (same silent-ignore class
+ * as `validateEc2ServiceSizing`).
+ */
+export function assertSharedAsgConfigMatches(serviceName, ec2Config, key, origin) {
+    // Cross-service only: the construction path legitimately re-resolves the
+    // SAME service's provider (e.g. a second task definition riding its ASG),
+    // and that re-entry must not trip the singleton throw.
+    if (origin.ec2Config.persistentDataVolume !== undefined &&
+        serviceName !== origin.serviceName) {
+        throw new Error(`Service '${serviceName}': its ec2Config resolves to the same EC2 capacity key ('${key}') ` +
+            `as service '${origin.serviceName}', whose persistentDataVolume pairs that auto scaling ` +
+            `group with a single EBS data volume. A persistent-data-volume service is a singleton — ` +
+            `two services sharing its ASG would race to attach the same volume. Change a keyed field ` +
+            `(${KEYED_ASG_FIELDS.map((f) => `'${f}'`).join(", ")}) so this service gets its own ASG.`);
+    }
+    const differing = findDifferingAsgFields(ec2Config, origin.ec2Config);
+    if (differing.length === 0)
+        return;
+    throw new Error(`Service '${serviceName}': ec2Config ${differing.map((f) => `'${f}'`).join(", ")} ` +
+        `${differing.length === 1 ? "is" : "are"} ignored — it shares an auto scaling group with ` +
+        `service '${origin.serviceName}' (both resolve to EC2 capacity key '${key}'), and that ASG ` +
+        `is built from the first service's ec2Config. Either give the two services the same value ` +
+        `for ${differing.map((f) => `'${f}'`).join(", ")}, or give this service its own ASG by ` +
+        `changing a keyed field (${KEYED_ASG_FIELDS.map((f) => `'${f}'`).join(", ")}).`);
+}
+/**
+ * Generates a unique key for EC2 config so services with matching
+ * configurations share an ASG.
+ */
+export function getEc2ConfigKey(ec2Config) {
+    const instanceType = ec2Config.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE;
+    const amiHardwareType = ec2Config.amiHardwareType ??
+        (inferAmiHardwareType(instanceType) === AmiHardwareType.ARM
+            ? "ARM"
+            : "STANDARD");
+    const warmPoolKey = ec2Config.warmPool
+        ? `wp${ec2Config.warmPool.minSize ?? DEFAULT_WARM_POOL_MIN_SIZE}-${ec2Config.warmPool.reuseOnScaleIn ?? DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN}`
+        : "nowp";
+    const baseKey = `${instanceType}-${amiHardwareType}-${warmPoolKey}`;
+    // PDV services are implicit singletons — two identical PDV configs still
+    // collide on this key, so sharing is rejected in assertSharedAsgConfigMatches.
+    const pdv = ec2Config.persistentDataVolume;
+    const extras = [];
+    if (pdv !== undefined) {
+        extras.push(`pdv-${pdv.deviceName}-${pdv.sizeGb}-${stableAzSegment(pdv.availabilityZone)}`);
+    }
+    // Serialise actual AZ names — `az${length}` would let services pinned to different AZs collide on `az1`.
+    // CDK Tokens (env-agnostic stacks) substitute a stable sentinel to keep logical IDs deterministic.
+    if (ec2Config.availabilityZones !== undefined) {
+        const azKey = [...ec2Config.availabilityZones]
+            .map(stableAzSegment)
+            .sort()
+            .join(",");
+        extras.push(`az-${azKey}`);
+    }
+    return extras.length === 0 ? baseKey : `${baseKey}-${extras.join("-")}`;
+}
+function stableAzSegment(az) {
+    return Token.isUnresolved(az) ? "synthAz" : az;
+}
+/**
+ * Cross-service shared-ASG compatibility: groups EC2 services by their
+ * capacity key and rejects a reuse that is incompatible with the ASG's origin
+ * — config drift the shared ASG would silently discard, or a
+ * `persistentDataVolume` singleton being shared. Pure; called from BOTH
+ * validation layers — resources `validateEcsClusterProps` and patterns
+ * `validateEcsProps` (generator-standards § "Validate at the Lowest Layer the
+ * Field Belongs To") — with the same check at the construction site
+ * (`getOrCreateAsgCapacityProvider`) as defence-in-depth.
+ */
+export function validateSharedEc2CapacityConfig(services) {
+    const origins = new Map();
+    for (const service of services) {
+        if (service.capacityProvider !== "EC2")
+            continue;
+        const ec2Config = service.ec2Config ?? {};
+        const key = getEc2ConfigKey(ec2Config);
+        const origin = origins.get(key);
+        if (origin === undefined) {
+            origins.set(key, { serviceName: service.name, ec2Config });
+            continue;
+        }
+        assertSharedAsgConfigMatches(service.name, ec2Config, key, origin);
+    }
+}

package/dist/lib/resources/aws/compute/ecsConstants.d.ts

@@ -1,3 +1,4 @@
+import { Monitoring } from "aws-cdk-lib/aws-autoscaling";
 import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
 import { RetentionDays } from "aws-cdk-lib/aws-logs";
 export declare const DEFAULT_EC2_INSTANCE_TYPE = "t4g.micro";
@@ -8,6 +9,23 @@ export declare const DEFAULT_LOG_RETENTION = RetentionDays.TWO_WEEKS;
 export declare const DEFAULT_FARGATE_CPU = 256;
 export declare const DEFAULT_FARGATE_MEMORY_MIB = 512;
 export declare const DEFAULT_EC2_CONTAINER_MEMORY_MIB = 1024;
+export declare const DEFAULT_EC2_MIN_CAPACITY = 2;
+export declare const DEFAULT_EC2_MAX_CAPACITY = 3;
+export declare const DEFAULT_EC2_INSTANCE_MONITORING = Monitoring.BASIC;
+/**
+ * The container hard memory limit for an EC2-capacity ECS service.
+ *
+ * Takes `ec2Config` and nothing else — deliberately. The service-level
+ * `memoryLimitMiB` is Fargate-only, and a `?? serviceProps.memoryLimitMiB`
+ * fallback here is the silent-ignore footgun `validateEc2ServiceSizing`
+ * exists to reject. Narrowing the parameter to the one field that may feed
+ * the derivation makes that fallback unrepresentable rather than merely
+ * discouraged: re-adding it requires widening this signature, which is a
+ * visible act in review. Do not widen it.
+ */
+export declare function resolveEc2ContainerMemoryMiB(ec2Config: {
+    readonly memoryLimitMiB?: number;
+} | undefined): number;
 export declare const DEFAULT_ECS_FALLBACK_IMAGE = "amazon/amazon-ecs-sample";
 export declare const DEFAULT_CUSTOM_RESOURCE_TIMEOUT_SECONDS = 300;
 export declare const DEFAULT_HEALTH_CHECK_GRACE_SECONDS = 120;

package/dist/lib/resources/aws/compute/ecsConstants.js

@@ -1,3 +1,4 @@
+import { Monitoring } from "aws-cdk-lib/aws-autoscaling";
 import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
 import { RetentionDays } from "aws-cdk-lib/aws-logs";
 // Canonical source: @fjall/generator schemas/constants.ts — keep in sync
@@ -16,6 +17,28 @@ export const DEFAULT_LOG_RETENTION = RetentionDays.TWO_WEEKS;
 export const DEFAULT_FARGATE_CPU = 256;
 export const DEFAULT_FARGATE_MEMORY_MIB = 512;
 export const DEFAULT_EC2_CONTAINER_MEMORY_MIB = 1024;
+// Read at two sites that must agree (code-quality § coupled values): the ASG
+// construction (`getOrCreateAsgCapacityProvider`) and the shared-ASG drift
+// compare (`ecsCapacityConfig.ts` SCALAR_ASG_FIELD_DEFAULTS) — the compare
+// resolves the same defaults the construction applies, or an explicit value
+// equal to the default would read as drift.
+export const DEFAULT_EC2_MIN_CAPACITY = 2;
+export const DEFAULT_EC2_MAX_CAPACITY = 3;
+export const DEFAULT_EC2_INSTANCE_MONITORING = Monitoring.BASIC;
+/**
+ * The container hard memory limit for an EC2-capacity ECS service.
+ *
+ * Takes `ec2Config` and nothing else — deliberately. The service-level
+ * `memoryLimitMiB` is Fargate-only, and a `?? serviceProps.memoryLimitMiB`
+ * fallback here is the silent-ignore footgun `validateEc2ServiceSizing`
+ * exists to reject. Narrowing the parameter to the one field that may feed
+ * the derivation makes that fallback unrepresentable rather than merely
+ * discouraged: re-adding it requires widening this signature, which is a
+ * visible act in review. Do not widen it.
+ */
+export function resolveEc2ContainerMemoryMiB(ec2Config) {
+    return ec2Config?.memoryLimitMiB ?? DEFAULT_EC2_CONTAINER_MEMORY_MIB;
+}
 // AWS sample image used when no ECR repository is provided. Consumed by both
 // the resources/ image resolver and the patterns/ defaults block — keep them
 // in lockstep via this single export.
@@ -46,10 +69,19 @@ export const ARM_INSTANCE_PREFIXES = [
     "r6gd",
     "r7g",
     "r7gd",
+    "r8g",
+    "r8gd",
+    "c8g",
+    "c8gd",
+    "c8gn",
     "m6g",
     "m6gd",
     "m7g",
     "m7gd",
+    "m8g",
+    "m8gd",
+    "x8g",
+    "i8g",
     "a1",
     "x2gd",
     "im4gn",

package/dist/lib/resources/aws/compute/ecsLifecycleHookMigration.js

@@ -49,7 +49,7 @@ export class EcsLifecycleHookMigration extends Construct {
                 : "DISABLED"
         };
         this.lambda = new LambdaFunction(this, `${id}Fn`, {
-            runtime: Runtime.NODEJS_22_X,
+            runtime: Runtime.NODEJS_24_X,
             handler: "index.handler",
             code: Code.fromInline(source),
             lambdaDescription: `${id} ECS deployment lifecycle hook for migration`,

package/dist/lib/resources/aws/compute/ecsServiceFactory.d.ts

@@ -3,7 +3,8 @@ import type { FargateTaskDefinition, Ec2TaskDefinition } from "aws-cdk-lib/aws-e
 import { type ISecurityGroup } from "aws-cdk-lib/aws-ec2";
 import { TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
 import { type AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
-import { type EcsServiceProps, type Ec2CapacityConfig, type QueueScalingResources } from "./ecsTypes.js";
+import { type Ec2AsgOrigin } from "./ecsCapacityConfig.js";
+import { type EcsServiceProps, type QueueScalingResources } from "./ecsTypes.js";
 import type { EcsConstructContext } from "./ecsContext.js";
 /**
  * Resolves the user's `circuitBreaker` config to the CDK
@@ -17,14 +18,16 @@ export declare function resolveCircuitBreaker(config: false | {
 /** Mutable state for ASG capacity provider deduplication. */
 export interface AsgCapacityState {
     providers: Map<string, AsgCapacityProvider>;
+    /**
+     * The service + ec2Config that first created each keyed ASG, so a later
+     * service sharing the key can be checked against it
+     * ({@link assertSharedAsgConfigMatches}).
+     */
+    asgOrigins: Map<string, Ec2AsgOrigin>;
     autoScalingGroup?: AutoScalingGroup;
     asgSecurityGroup?: ISecurityGroup;
 }
-/**
- * Generates a unique key for EC2 config so services with matching
- * configurations share an ASG.
- */
-export declare function getEc2ConfigKey(ec2Config: Ec2CapacityConfig): string;
+export { getEc2ConfigKey, validateSharedEc2CapacityConfig, type Ec2AsgOrigin, type SharedEc2CapacityServiceInput } from "./ecsCapacityConfig.js";
 /**
  * Gets or creates an ASG capacity provider for an EC2-backed service.
  * Services with matching EC2 configs share the same ASG.

package/dist/lib/resources/aws/compute/ecsServiceFactory.js

@@ -2,16 +2,16 @@ import { FargateService, Ec2Service, PropagatedTagSource, PlacementStrategy, Asg
 import { Peer, Port, SubnetType, UserData } from "aws-cdk-lib/aws-ec2";
 import { ServicePrincipal } from "aws-cdk-lib/aws-iam";
 import { Role } from "../iam/role.js";
-import { CfnOutput, Duration, Token } from "aws-cdk-lib";
+import { CfnOutput, Duration } from "aws-cdk-lib";
 import { AdjustmentType, PredefinedMetric, ScalableTarget, ServiceNamespace, StepScalingAction, TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
 import { Alarm, ComparisonOperator, MathExpression } from "aws-cdk-lib/aws-cloudwatch";
 import { ApplicationScalingAction } from "aws-cdk-lib/aws-cloudwatch-actions";
-import { Monitoring } from "aws-cdk-lib/aws-autoscaling";
 import { SecurityGroup } from "../networking/securityGroup.js";
 import { Ec2Instance } from "./ec2.js";
 import { vpcHasNatGateways } from "../../../utils/vpcUtils.js";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
-import { DEFAULT_EC2_INSTANCE_TYPE, DEFAULT_WARM_POOL_MIN_SIZE, DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN, DEFAULT_HEALTH_CHECK_GRACE_SECONDS, DEFAULT_MIN_HEALTHY_PERCENT, DEFAULT_MAX_HEALTHY_PERCENT, DEFAULT_DESIRED_COUNT, inferAmiHardwareType } from "./ecsConstants.js";
+import { DEFAULT_EC2_INSTANCE_TYPE, DEFAULT_EC2_MIN_CAPACITY, DEFAULT_EC2_MAX_CAPACITY, DEFAULT_EC2_INSTANCE_MONITORING, DEFAULT_WARM_POOL_MIN_SIZE, DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN, DEFAULT_HEALTH_CHECK_GRACE_SECONDS, DEFAULT_MIN_HEALTHY_PERCENT, DEFAULT_MAX_HEALTHY_PERCENT, DEFAULT_DESIRED_COUNT, inferAmiHardwareType } from "./ecsConstants.js";
+import { assertSharedAsgConfigMatches, getEc2ConfigKey } from "./ecsCapacityConfig.js";
 import { ScalingType } from "./ecsTypes.js";
 import { isServiceFargate, isServiceEc2 } from "./ecsTaskDefinition.js";
 /**
@@ -26,40 +26,7 @@ export function resolveCircuitBreaker(config) {
     const rollback = config?.rollback ?? true;
     return { enable: true, rollback };
 }
-/**
- * Generates a unique key for EC2 config so services with matching
- * configurations share an ASG.
- */
-export function getEc2ConfigKey(ec2Config) {
-    const instanceType = ec2Config.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE;
-    const amiHardwareType = ec2Config.amiHardwareType ??
-        (inferAmiHardwareType(instanceType) === AmiHardwareType.ARM
-            ? "ARM"
-            : "STANDARD");
-    const warmPoolKey = ec2Config.warmPool
-        ? `wp${ec2Config.warmPool.minSize ?? DEFAULT_WARM_POOL_MIN_SIZE}-${ec2Config.warmPool.reuseOnScaleIn ?? DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN}`
-        : "nowp";
-    const baseKey = `${instanceType}-${amiHardwareType}-${warmPoolKey}`;
-    // PDV services are implicit singletons — sharing an ASG would let two tasks race for the same EBS volume.
-    const pdv = ec2Config.persistentDataVolume;
-    const extras = [];
-    if (pdv !== undefined) {
-        extras.push(`pdv-${pdv.deviceName}-${pdv.sizeGb}-${stableAzSegment(pdv.availabilityZone)}`);
-    }
-    // Serialise actual AZ names — `az${length}` would let services pinned to different AZs collide on `az1`.
-    // CDK Tokens (env-agnostic stacks) substitute a stable sentinel to keep logical IDs deterministic.
-    if (ec2Config.availabilityZones !== undefined) {
-        const azKey = [...ec2Config.availabilityZones]
-            .map(stableAzSegment)
-            .sort()
-            .join(",");
-        extras.push(`az-${azKey}`);
-    }
-    return extras.length === 0 ? baseKey : `${baseKey}-${extras.join("-")}`;
-}
-function stableAzSegment(az) {
-    return Token.isUnresolved(az) ? "synthAz" : az;
-}
+export { getEc2ConfigKey, validateSharedEc2CapacityConfig } from "./ecsCapacityConfig.js";
 /**
  * Gets or creates an ASG capacity provider for an EC2-backed service.
  * Services with matching EC2 configs share the same ASG.
@@ -71,8 +38,13 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
     const key = getEc2ConfigKey(ec2Config);
     const existing = state.providers.get(key);
     if (existing) {
+        const origin = state.asgOrigins.get(key);
+        if (origin !== undefined) {
+            assertSharedAsgConfigMatches(serviceProps.name, ec2Config, key, origin);
+        }
         return existing;
     }
+    state.asgOrigins.set(key, { serviceName: serviceProps.name, ec2Config });
     const safeKey = key.replace(/[^a-zA-Z0-9]/g, "");
     const instanceType = ec2Config.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE;
     const amiHardwareType = ec2Config.amiHardwareType
@@ -80,8 +52,8 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
             ? AmiHardwareType.STANDARD
             : AmiHardwareType.ARM
         : inferAmiHardwareType(instanceType);
-    const minCapacity = ec2Config.minCapacity ?? 2;
-    const maxCapacity = ec2Config.maxCapacity ?? 3;
+    const minCapacity = ec2Config.minCapacity ?? DEFAULT_EC2_MIN_CAPACITY;
+    const maxCapacity = ec2Config.maxCapacity ?? DEFAULT_EC2_MAX_CAPACITY;
     const asgSecurityGroup = ctx.props.cluster?.securityGroup ??
         new SecurityGroup(ctx.scope, `${safeKey}AsgSecurityGroup`, {
             vpc: ctx.cluster.vpc,
@@ -129,7 +101,7 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
             EcsOptimizedImage.amazonLinux2023(amiHardwareType),
         userData: ec2Config.userData ?? UserData.forLinux(),
         role: instanceRole,
-        instanceMonitoring: ec2Config.instanceMonitoring ?? Monitoring.BASIC,
+        instanceMonitoring: ec2Config.instanceMonitoring ?? DEFAULT_EC2_INSTANCE_MONITORING,
         capacityRebalance: true,
         ecsClusterArn: ctx.cluster.clusterArn,
         ...(ec2Config.desiredCapacity !== undefined && {
@@ -160,7 +132,11 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
         // MTP's ProtectedFromScaleIn flag does NOT clear on CP deletion, so
         // CFN rollback wedges on a stranded protected instance. The drain
         // path is Ec2GracefulTerminationHandler instead.
-        enableManagedTerminationProtection: false
+        enableManagedTerminationProtection: false,
+        // A min=max pinned ASG cannot scale; managed scaling would still mint a
+        // CapacityProviderReservation target-tracking pair that wedges in ALARM
+        // whenever a task cannot place (2026-07-24 ClickHouse phantom task).
+        enableManagedScaling: minCapacity !== maxCapacity
     });
     ctx.cluster.addAsgCapacityProvider(provider);
     state.providers.set(key, provider);

package/dist/lib/resources/aws/compute/ecsTaskDefinition.js

@@ -5,7 +5,7 @@ import { StringParameter } from "aws-cdk-lib/aws-ssm";
 import { buildParameterPath } from "@fjall/util";
 import { resolveOrgId } from "../../../utils/cdkContext.js";
 import { validateSsmPathComponent, validateSecretName } from "./ecsValidation.js";
-import { DEFAULT_LOG_RETENTION, DEFAULT_FARGATE_CPU, DEFAULT_FARGATE_MEMORY_MIB, DEFAULT_EC2_CONTAINER_MEMORY_MIB } from "./ecsConstants.js";
+import { DEFAULT_LOG_RETENTION, DEFAULT_FARGATE_CPU, DEFAULT_FARGATE_MEMORY_MIB, resolveEc2ContainerMemoryMiB } from "./ecsConstants.js";
 import { LogGroup } from "../logging/logGroup.js";
 import { getContainerImage } from "./ecsImages.js";
 import { resolveRemoteConnections } from "./ecsRemoteConnections.js";
@@ -214,12 +214,8 @@ export function addContainersToTask(ctx, serviceName, serviceProps, taskDefiniti
             stopTimeout: containerConfig.stopTimeout !== undefined
                 ? Duration.seconds(containerConfig.stopTimeout)
                 : undefined,
-            // EC2 container memory is ec2Config-only by design — do NOT add a
-            // `?? serviceProps.memoryLimitMiB` fallback (that is the silent-ignore
-            // footgun `validateEc2ServiceSizing` exists to reject).
             ...(isServiceEc2(serviceProps) && {
-                memoryLimitMiB: serviceProps.ec2Config?.memoryLimitMiB ??
-                    DEFAULT_EC2_CONTAINER_MEMORY_MIB
+                memoryLimitMiB: resolveEc2ContainerMemoryMiB(serviceProps.ec2Config)
             })
         });
         if (containerConfig.port !== undefined &&

package/dist/lib/resources/aws/compute/ecsValidation.js

@@ -3,6 +3,7 @@ import { evaluateBakeGuard } from "@fjall/util/docker";
 import { toKebab, SSM_COMPONENT_PATTERN, SSM_COMPONENT_ERROR, SECRET_NAME_PATTERN, SECRET_NAME_ERROR } from "@fjall/util";
 import { ScalingType } from "./ecsTypes.js";
 import { DEFAULT_EC2_CONTAINER_MEMORY_MIB } from "./ecsConstants.js";
+import { validateSharedEc2CapacityConfig } from "./ecsCapacityConfig.js";
 /**
  * Validates ECS cluster props before construction.
  * Pure function — does not depend on class state.
@@ -156,12 +157,19 @@ export function validateEcsClusterProps(props) {
         // backlog scaling — CPU/MEMORY target-tracking produces no datapoint at
         // zero running tasks, so DesiredCount never rises (the 2026-06-04
         // asset-discovery outage). Reject the un-wakeable shape at synth.
+        // scalingType undefined means scaling was EXPLICITLY disabled
+        // (resolveScalingConfig defaults undefined input to CPU): no policy exists
+        // to wake the service, so desiredCount 0 is a deliberately parked service
+        // (the ClickHouse bring-up escape hatch), not the trap.
         if (service.desiredCount === 0 &&
+            service.scalingType !== undefined &&
             service.scalingType !== ScalingType.QUEUE) {
             throw new Error(`Service '${service.name}': desiredCount is 0 but scalingType is ` +
-                `${service.scalingType ?? "unset"} — a service that starts at zero can ` +
+                `${service.scalingType} — a service that starts at zero can ` +
                 "only wake on queue backlog. Use ScalingType.QUEUE with queueScaling.queues " +
-                "so it scales up from 0, or raise desiredCount to keep at least one task running. " +
+                "so it scales up from 0, raise desiredCount to keep at least one task running, " +
+                "or disable scaling to park the service deliberately (patterns layer: " +
+                "scaling: false; resources layer: omit scalingType). " +
                 "CPU/MEMORY target-tracking produces no datapoint at zero tasks and never scales up.");
         }
         if (service.scalingType === ScalingType.QUEUE) {
@@ -189,6 +197,11 @@ export function validateEcsClusterProps(props) {
             }
         }
     }
+    // Cross-service, so it runs after the per-service loop: EC2 services whose
+    // ec2Config resolves to the same capacity key share one ASG — reject config
+    // drift the shared ASG would silently discard, and any sharing of a
+    // persistentDataVolume (singleton) ASG.
+    validateSharedEc2CapacityConfig(props.services);
 }
 /**
  * Rejects service-level task sizing that is silently ignored for EC2 capacity.

package/dist/lib/resources/aws/compute/persistentDataVolume.js

@@ -157,7 +157,7 @@ export class PersistentDataVolume extends Construct {
             resources: [asgArnWildcard]
         });
         this.lambda = new LambdaFunction(this, `${id}Fn`, {
-            runtime: Runtime.NODEJS_22_X,
+            runtime: Runtime.NODEJS_24_X,
             handler: "index.handler",
             code: Code.fromInline(source),
             lambdaDescription: `${id} ${PERSISTENT_DATA_VOLUME_LAUNCHING_DESCRIPTION}`,

package/dist/lib/resources/aws/database/clickhouseConstants.d.ts

@@ -14,10 +14,15 @@ export declare const CLICKHOUSE_DATABASE_NAME = "analytics";
  *  max_concurrent_queries=8) — see clickhouseUserData.ts. Bumping to a larger
  *  instance MUST be paired with raising those thread/concurrency caps.
  *
- *  Next size up: `m7g.large` (2 vCPU, 8 GiB) for sustained workloads, or
- *  `r7g.medium` (1 vCPU, 8 GiB) when memory-bound. Set via
- *  `clickhouseInstanceType` CDK context or the `instanceType` prop, no code
- *  change needed (see clickhouseDatabase.ts:162). */
+ *  Next size up (2026-07-31 right-sizing, designs/2026-07-31-clickhouse-
+ *  factory-fit-for-purpose.md): `r8g.medium` (1 vCPU Graviton4, 8 GiB,
+ *  ~+30%/core over Graviton3) — CH's own doctrine floors production at
+ *  8 GiB, and the memory-bound single-tenant profile wants RAM before
+ *  cores. `m7g.large` (2 vCPU, 8 GiB) only when CPU-bound. Set via
+ *  `clickhouseInstanceType` CDK context or the `instanceType` prop —
+ *  the container memory limit derives automatically via
+ *  `clickHouseTaskMemoryMiB()`, but the thread/concurrency caps in
+ *  clickhouseUserData.ts still need a lockstep re-tune. */
 export declare const DEFAULT_CLICKHOUSE_INSTANCE_TYPE = "m7g.medium";
 /** ClickHouse container image. Explicit `docker.io/` prefix is required so
  *  string-form consumers in `ecsImages.ts#getContainerImage()` route through
@@ -38,17 +43,35 @@ export declare const DEFAULT_CLICKHOUSE_INSTANCE_TYPE = "m7g.medium";
  *  Image size is ~250 MB larger but irrelevant on a single-instance EC2 ASG
  *  that pulls once per launch. Upstream CH CI runs its full perf + stress
  *  matrix on the Ubuntu build; Alpine is community-tier coverage. */
-export declare const CLICKHOUSE_IMAGE = "docker.io/clickhouse/clickhouse-server:26.3.10.60";
+export declare const CLICKHOUSE_IMAGE = "docker.io/clickhouse/clickhouse-server:26.3.17.56";
 /** EBS volume configuration. */
 export declare const CLICKHOUSE_EBS_VOLUME_SIZE_GB = 80;
 export declare const CLICKHOUSE_EBS_IOPS = 3000;
 export declare const CLICKHOUSE_EBS_THROUGHPUT_MBPS = 125;
-/** ECS task resource allocation. m7g.medium ships with 4 GB; reserve 1 GB
- *  for the host (kernel + ECS agent + cloudwatch agent + IMDS) and give
- *  ClickHouse the remaining 3 GB. Stays right when bumping to m7g.large
- *  (8 GB) — raise this value in lockstep, or fall back to deriving from
- *  the instance type if we ever support multiple sizes. */
-export declare const CLICKHOUSE_TASK_MEMORY_MIB = 3072;
+/** Host memory reserved from the ClickHouse container: kernel + ECS agent +
+ *  the host-metrics timer. The ECS agent advertises MemTotal minus
+ *  CLICKHOUSE_ECS_RESERVED_MEMORY_MIB, and MemTotal itself runs below the
+ *  AWS nominal figure (firmware carve-outs plus page-struct overhead that
+ *  grows with RAM, ~205 MiB observed on the 4 GiB m7g.medium), so this
+ *  reserve must absorb both or the task never places. 1 GiB is proven at
+ *  4–16 GiB; the ≥32 GiB rows double it (see clickHouseTaskMemoryMiB). */
+export declare const CLICKHOUSE_HOST_RESERVE_MIB = 1024;
+/** MiB the ECS agent withholds from advertised capacity — written to
+ *  /etc/ecs/ecs.config as `ECS_RESERVED_MEMORY` by buildClickHouseUserData.
+ *  Must stay well inside CLICKHOUSE_HOST_RESERVE_MIB: the container limit is
+ *  derived from nominal memory, so the host reserve is what absorbs this
+ *  withholding at task placement. */
+export declare const CLICKHOUSE_ECS_RESERVED_MEMORY_MIB = 256;
+/** Total memory (GiB) of the instance types the ClickHouse construct knows
+ *  how to size a container for. Values are the AWS nominal figures. */
+export declare const CLICKHOUSE_INSTANCE_MEMORY_GIB: Record<string, number>;
+/** ECS container memory for the ClickHouse server task, derived from the
+ *  instance type so a size change cannot leave the hand-set container cap
+ *  behind (the pre-2026-07 shape: a hardcoded 3072 that silently starved —
+ *  or over-committed — any non-4-GiB host). Unknown types throw at synth:
+ *  a memoryLimitMiB above what the host advertises strands the task in
+ *  PROVISIONING with no CloudFormation error. */
+export declare function clickHouseTaskMemoryMiB(instanceType: string): number;
 /** ClickHouse ports. */
 export declare const CLICKHOUSE_HTTP_PORT = 8123;
 export declare const CLICKHOUSE_NATIVE_PORT = 9000;
@@ -58,22 +81,16 @@ export declare const CLICKHOUSE_PROMETHEUS_PORT = 9363;
  *  See aiDocs/patterns/clickhouse-tls-pattern.md § "The contract". */
 export declare const CLICKHOUSE_HTTPS_PORT = 8443;
 export declare const CLICKHOUSE_TCP_SECURE_PORT = 9440;
-/** Mount path inside the main ClickHouse container for the materialised
- *  TLS cert + key. The init container writes to a shared task-scoped volume
- *  mounted here read-only on the main container. */
+/** Mount path inside the ClickHouse container for the materialised TLS cert
+ *  + key. The EC2 user-data bootstrap (`buildClickHouseUserData` tlsBootstrap)
+ *  fetches the PEMs from Secrets Manager onto the EBS data volume at
+ *  `<mount>/server-certs`, which is bind-mounted read-only into the container
+ *  at this path. */
 export declare const CLICKHOUSE_TLS_CERT_MOUNT_PATH = "/etc/clickhouse-server/certs";
-/** Task-scoped Docker volume name shared between the TLS init container
- *  (writer) and the main ClickHouse container (reader). */
-export declare const CLICKHOUSE_TLS_CERT_VOLUME_NAME = "tls-certs";
-/** UID:GID the official ClickHouse image runs as. Init container `chown`s
- *  the materialised cert files to this UID so the server can read them. */
+/** UID:GID the official ClickHouse image runs as. The user-data bootstrap
+ *  `chown`s the materialised cert files to this UID so the server can read
+ *  them. */
 export declare const CLICKHOUSE_UID = 101;
-/** Digest-pinned alpine image used by the TLS init container. The init
- *  container needs `jq` (extracts `cert`+`key` from the server-cert JSON
- *  secret); alpine ships it via `apk add` — but pinning the digest avoids
- *  fetching `:latest` on every deploy. Bump in lockstep with renovate
- *  alerts; CI verifies the digest resolves. */
-export declare const ALPINE_INIT_CONTAINER_IMAGE = "public.ecr.aws/docker/library/alpine:3.20@sha256:beefdbd8a1da6d2915566fde36db9db0b524eb737fc57cd1367effd16dc0d06d";
 /** EBS device name for the data volume (must match user data script). */
 export declare const CLICKHOUSE_EBS_DEVICE_NAME = "/dev/xvdf";
 /** EBS mount path on the EC2 host. */
@@ -123,6 +140,22 @@ export declare const CLICKHOUSE_SERVER_ROLE_TAG: {
     readonly key: "ClickHouseRole";
     readonly value: "server";
 };
+/** CloudWatch identity of the host metrics: namespace, metric names, and the
+ *  dimension key. Three sites consume this and they MUST match: (a) the
+ *  user-data put-metric-data timer (`buildClickHouseUserData`) that publishes
+ *  the datapoints, (b) the host alarms (`createClickHouseAlarms`) that
+ *  consume them, and (c) the instance-role PutMetricData namespace condition
+ *  (`clickhouseDatabase.ts`). One-character drift re-blinds the alarms
+ *  silently — and with disk-critical on TreatMissingData.BREACHING, a
+ *  namespace typo pages as a phantom full disk. "CWAgent" matches what the
+ *  CloudWatch Agent would publish, keeping dashboards portable if the timer
+ *  is ever replaced by the real agent. */
+export declare const CLICKHOUSE_HOST_METRICS: {
+    readonly namespace: "CWAgent";
+    readonly memoryMetric: "mem_used_percent";
+    readonly diskMetric: "disk_used_percent";
+    readonly asgDimension: "AutoScalingGroupName";
+};
 /** Shared secret generation options (all ClickHouse users share the same policy). */
 export declare const CLICKHOUSE_SECRET_OPTIONS: {
     readonly excludePunctuation: true;