@fjall/components-infrastructure 10.1.3 → 12.0.0

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

@@ -20,10 +20,13 @@ export interface ClickHouseDatabaseProps {
     /** EC2 instance type. Default: `m7g.medium` (1 vCPU sustained, 4 GiB);
      *  recommended step-up `r8g.medium` (8 GiB — see
      *  `DEFAULT_CLICKHOUSE_INSTANCE_TYPE`). Must appear in
-     *  `CLICKHOUSE_INSTANCE_MEMORY_GIB` — the container memory limit derives
-     *  from it via `clickHouseTaskMemoryMiB()` and unknown types throw at
-     *  synth. CH user-data is tuned for 1 vCPU; raise per-user `max_threads`
-     *  and `max_concurrent_queries` if bumping to a >=2 vCPU host.
+     *  `CLICKHOUSE_INSTANCE_SPECS` — the container memory limit
+     *  (`clickHouseTaskMemoryMiB()`), the server pools/caches
+     *  (`deriveClickHouseServerTuning()`) and the default profiles
+     *  (`deriveClickHouseDefaultProfiles()`) ALL derive from it, and unknown
+     *  types throw at synth. Server-side values are baked into EC2 user-data:
+     *  taking a new type live needs a launch-template refresh + instance
+     *  refresh + ClickHouse restart, not a config reload.
      *
      *  WARNING — changing this on a DEPLOYED stack REPLACES the persistent
      *  data volume, not just the instance. The instance type is embedded in
@@ -103,9 +106,12 @@ export interface ClickHouseDatabaseProps {
     managedPasswords?: string[];
     /**
      * Per-profile resource caps. Profile keys MUST match lowercase snake_case
-     * (`^[a-z][a-z0-9_]*$`). Defaults to `ClickHouseDefaultProfiles` when
-     * omitted — four workload-class profiles
-     * (`high_throughput_ingest`, `audit_append`, `read_only`, `ddl_admin`).
+     * (`^[a-z][a-z0-9_]*$`). Defaults to the four workload-class profiles
+     * (`high_throughput_ingest`, `audit_append`, `read_only`, `ddl_admin`)
+     * derived from the RESOLVED instance type via
+     * `deriveClickHouseDefaultProfiles()` — memory caps and thread counts
+     * track the host. Supplying this prop replaces the derived defaults
+     * wholesale (no merge), so an explicit map opts out of instance scaling.
      *
      * Throws `Error` on validation failure — unknown profile fields,
      * non-snake_case names.

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

@@ -20,9 +20,10 @@ import { buildClickHouseEntrypointWrapper, buildClickHouseUserData, generateUser
 import { toPascalCase } from "../../utils/capitaliseString.js";
 import { resolveAlertsTopic } from "../../utils/resolveAlertsTopic.js";
 import { createClickHouseAlarms } from "../../resources/aws/monitoring/index.js";
-import { ClickHouseSchemaAdminSchema, ManagedPasswordNameSchema, ProfileSpecSchema, ClickHouseDefaultProfiles, PROFILE_NAME_PATTERN } from "../../resources/aws/database/clickhouseSchemas.js";
+import { ClickHouseSchemaAdminSchema, ManagedPasswordNameSchema, ProfileSpecSchema, PROFILE_NAME_PATTERN } from "../../resources/aws/database/clickhouseSchemas.js";
+import { deriveClickHouseDefaultProfiles } from "../../resources/aws/database/clickhouseTuning.js";
 import { inferAmiHardwareType } from "../../resources/aws/compute/ecsConstants.js";
-import { CLICKHOUSE_DATABASE_NAME, DEFAULT_CLICKHOUSE_INSTANCE_TYPE, CLICKHOUSE_IMAGE, CLICKHOUSE_EBS_VOLUME_SIZE_GB, CLICKHOUSE_EBS_IOPS, CLICKHOUSE_EBS_THROUGHPUT_MBPS, clickHouseTaskMemoryMiB, CLICKHOUSE_HTTP_PORT, CLICKHOUSE_HTTPS_PORT, CLICKHOUSE_NATIVE_PORT, CLICKHOUSE_TCP_SECURE_PORT, CLICKHOUSE_TLS_CERT_MOUNT_PATH, CLICKHOUSE_PROMETHEUS_PORT, CLICKHOUSE_DATA_MOUNT_PATH, CLICKHOUSE_SECRET_OPTIONS, CLICKHOUSE_SERVER_ROLE_TAG, CLICKHOUSE_HOST_METRICS, clickHouseUserSecretName, CLICKHOUSE_HEALTH_CHECK, CLICKHOUSE_STOP_TIMEOUT_SECONDS, CLICKHOUSE_EBS_DEVICE_NAME, CLICKHOUSE_CONFIG_SUBDIR, CLICKHOUSE_USERS_SUBDIR, userPasswordEnvName, OPTIMISE_FINAL_SCHEDULE, REPLACING_MERGE_TREE_TABLES, OPTIMISE_MV_TABLES, CLICKHOUSE_CLOUDMAP_SERVICE_NAME, CLICKHOUSE_SERVER_CONTAINER_NAME, OPTIMISE_TASK_MEMORY_MIB, OPTIMISE_TASK_CPU_UNITS, BACKUP_SCHEDULE, BACKUP_TASK_MEMORY_MIB, BACKUP_TASK_CPU_UNITS, BACKUP_RETENTION_DAYS } from "../../resources/aws/database/clickhouseConstants.js";
+import { CLICKHOUSE_DATABASE_NAME, DEFAULT_CLICKHOUSE_INSTANCE_TYPE, CLICKHOUSE_IMAGE, CLICKHOUSE_EBS_VOLUME_SIZE_GB, CLICKHOUSE_EBS_IOPS, CLICKHOUSE_EBS_THROUGHPUT_MBPS, clickHouseTaskMemoryMiB, CLICKHOUSE_HTTP_PORT, CLICKHOUSE_HTTPS_PORT, CLICKHOUSE_NATIVE_PORT, CLICKHOUSE_TCP_SECURE_PORT, CLICKHOUSE_TLS_CERT_MOUNT_PATH, CLICKHOUSE_PROMETHEUS_PORT, CLICKHOUSE_DATA_MOUNT_PATH, CLICKHOUSE_SECRET_OPTIONS, CLICKHOUSE_SERVER_ROLE_TAG, CLICKHOUSE_HOST_METRICS, clickHouseUserSecretName, CLICKHOUSE_HEALTH_CHECK, CLICKHOUSE_STOP_TIMEOUT_SECONDS, CLICKHOUSE_EBS_DEVICE_NAME, CLICKHOUSE_CONFIG_SUBDIR, CLICKHOUSE_USERS_SUBDIR, userPasswordEnvName, OPTIMISE_FINAL_SCHEDULE, REPLACING_MERGE_TREE_TABLES, OPTIMISE_MV_TABLES, CLICKHOUSE_CLOUDMAP_SERVICE_NAME, CLICKHOUSE_SERVER_CONTAINER_NAME, CLICKHOUSE_SERVICE_NAME, OPTIMISE_TASK_MEMORY_MIB, OPTIMISE_TASK_CPU_UNITS, BACKUP_SCHEDULE, BACKUP_TASK_MEMORY_MIB, BACKUP_TASK_CPU_UNITS, BACKUP_RETENTION_DAYS } from "../../resources/aws/database/clickhouseConstants.js";
 import { TlsCertGenerator } from "../../resources/aws/utilities/tlsCertGenerator.js";
 import { EcsCompute } from "./computeEcs.js";
 /**
@@ -134,7 +135,20 @@ export class ClickHouseDatabase extends Construct {
             throw new Error(`ClickHouseDatabase: invalid managedPasswords: prop — ${managedPasswordsParse.error.message}`);
         }
         const managedPasswords = managedPasswordsParse.data;
-        const profiles = props.profiles ?? ClickHouseDefaultProfiles;
+        const contextValue = this.node.tryGetContext("clickhouseInstanceType");
+        const contextInstanceType = typeof contextValue === "string" && contextValue !== ""
+            ? contextValue
+            : undefined;
+        const propInstanceType = props.instanceType !== undefined && props.instanceType !== ""
+            ? props.instanceType
+            : undefined;
+        const instanceType = contextInstanceType ??
+            propInstanceType ??
+            DEFAULT_CLICKHOUSE_INSTANCE_TYPE;
+        // Default profiles derive from the RESOLVED instance type so memory caps
+        // and thread counts track the actual host — a caller-supplied `profiles:`
+        // map opts out of scaling entirely (their values, their responsibility).
+        const profiles = props.profiles ?? deriveClickHouseDefaultProfiles(instanceType);
         const ProfilesRecordSchema = z.record(z
             .string()
             .regex(PROFILE_NAME_PATTERN, "Profile name must be lowercase snake_case"), ProfileSpecSchema);
@@ -157,16 +171,6 @@ export class ClickHouseDatabase extends Construct {
             schemaAdmin.name,
             ...managedPasswords
         ];
-        const contextValue = this.node.tryGetContext("clickhouseInstanceType");
-        const contextInstanceType = typeof contextValue === "string" && contextValue !== ""
-            ? contextValue
-            : undefined;
-        const propInstanceType = props.instanceType !== undefined && props.instanceType !== ""
-            ? props.instanceType
-            : undefined;
-        const instanceType = contextInstanceType ??
-            propInstanceType ??
-            DEFAULT_CLICKHOUSE_INSTANCE_TYPE;
         const desiredCount = resolveClickHouseDesiredCount(this.node.tryGetContext("clickhouseDesiredCount"), props.desiredCount);
         const optimiseEnabled = props.optimiseSchedule !== false;
         const backupEnabled = props.backupSchedule !== false;
@@ -258,6 +262,7 @@ export class ClickHouseDatabase extends Construct {
         const userData = UserData.custom(buildClickHouseUserData({
             backupBucketName: backupBucket.bucketName,
             backupBucketRegion: Stack.of(this).region,
+            instanceType,
             ...(coldTierBucket !== undefined && {
                 coldTier: {
                     bucketName: coldTierBucket.bucketName,
@@ -372,7 +377,7 @@ export class ClickHouseDatabase extends Construct {
             },
             services: [
                 {
-                    name: "ClickHouseService",
+                    name: CLICKHOUSE_SERVICE_NAME,
                     capacityProvider: "EC2",
                     desiredCount,
                     // Omitting `scaling` attaches default CPU target tracking. A scaled-out
@@ -484,9 +489,9 @@ export class ClickHouseDatabase extends Construct {
                 }
             ]
         });
-        const clickHouseTaskDef = ecsCompute.getTaskDefinition("ClickHouseService");
+        const clickHouseTaskDef = ecsCompute.getTaskDefinition(CLICKHOUSE_SERVICE_NAME);
         if (!clickHouseTaskDef) {
-            throw new Error("ClickHouseDatabase: EcsCompute did not expose a ClickHouseService task definition — expected the service to be registered.");
+            throw new Error(`ClickHouseDatabase: EcsCompute did not expose a ${CLICKHOUSE_SERVICE_NAME} task definition — expected the service to be registered.`);
         }
         backupBucket.grantReadWrite(clickHouseTaskDef.taskRole);
         coldTierBucket?.grantReadWrite(clickHouseTaskDef.taskRole);

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

@@ -28,7 +28,7 @@ import { evaluateBakeGuard } from "@fjall/util/docker";
 import { toKebab, buildParameterPath } from "@fjall/util";
 import { SCHEMA_GATE_CH_CA_CERT_ENV, SCHEMA_GATE_CH_DATABASE_ENV, SCHEMA_GATE_CH_URL_ENV, SCHEMA_GATE_CONTAINER_NAME, SCHEMA_GATE_DB_URL_BASE_ENV, SCHEMA_GATE_ECR_REPO_NAME } from "@fjall/util/migration";
 import { CONSTRUCTS_VERSION } from "../../utils/engineCompat.js";
-import { validateEc2ServiceSizing, validateEcsDomainConfig, validateSecretName } from "../../resources/aws/compute/ecsValidation.js";
+import { validateEc2ServiceSizing, validateEc2TaskMemoryFit, validateEcsDomainConfig, validateSecretName } from "../../resources/aws/compute/ecsValidation.js";
 import { validateSharedEc2CapacityConfig } from "../../resources/aws/compute/ecsCapacityConfig.js";
 import { COMPUTE_DEFAULTS, collectImportedSecretNames } from "./compute.js";
 import { isHookMigrations, normaliseSchemaGate } from "./computeEcsTypes.js";
@@ -183,6 +183,12 @@ export function validateEcsProps(props) {
                 "The ec2Config will be ignored unless capacityProvider is set to 'EC2'.");
         }
         validateEc2ServiceSizing(service);
+        // Throw-only at this layer: the gate container is not yet injected here
+        // (wireSchemaGate prepends it later), so the demand under-counts by the
+        // gate's 512 MiB — a conservative early throw. The resources-layer call
+        // in validateEcsClusterProps sees the final wired containers and also
+        // emits the non-fatal warnings.
+        validateEc2TaskMemoryFit(service);
         if (typeof service.circuitBreaker === "object") {
             const threshold = service.circuitBreaker.threshold;
             if (threshold !== undefined &&

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

@@ -825,7 +825,7 @@ export interface EcsServiceConfig {
      * {
      *   services: [
      *     { name: "api", capacityProvider: "FARGATE" },
-     *     { name: "worker", capacityProvider: "EC2", ec2Config: { instanceType: "t4g.micro" } }
+     *     { name: "worker", capacityProvider: "EC2", ec2Config: { instanceType: "t4g.small" } }
      *   ]
      * }
      */

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

@@ -94,7 +94,7 @@ export default class EcsCluster extends Construct {
         this.directAccessEnabled = props.cluster?.directAccess === true;
         this.loadBalancerDisabled =
             props.cluster?.loadBalancer === false || this.directAccessEnabled;
-        validateEcsClusterProps(props);
+        validateEcsClusterProps(props, this);
         this.cluster = this.addCluster(props);
         for (const serviceProps of props.services) {
             if (serviceProps.capacityProvider === "EC2") {

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

@@ -2,7 +2,7 @@ import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
 import { Token } from "aws-cdk-lib";
 import { CAPACITY_ANCHOR_MAX_LENGTH, CAPACITY_ANCHOR_PATTERN, CAPACITY_SLOT_MAX_LENGTH, CAPACITY_SLOT_PATTERN, DEFAULT_CAPACITY_SLOT } from "@fjall/util";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
-import { DEFAULT_EC2_INSTANCE_TYPE, DEFAULT_EC2_MIN_CAPACITY, DEFAULT_EC2_MAX_CAPACITY, DEFAULT_EC2_INSTANCE_MONITORING, DEFAULT_ROLLING_UPDATE_PAUSE_SECONDS, DEFAULT_WARM_POOL_MIN_SIZE, DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN, INSTANCE_REFRESH_DEFAULT_MAX_HEALTHY, INSTANCE_REFRESH_DEFAULT_MIN_HEALTHY, INSTANCE_REFRESH_PDV_MAX_HEALTHY, INSTANCE_REFRESH_PDV_MIN_HEALTHY, inferAmiHardwareType } from "./ecsConstants.js";
+import { DEFAULT_ECS_EC2_INSTANCE_TYPE, DEFAULT_EC2_MIN_CAPACITY, DEFAULT_EC2_MAX_CAPACITY, DEFAULT_EC2_INSTANCE_MONITORING, DEFAULT_ROLLING_UPDATE_PAUSE_SECONDS, DEFAULT_WARM_POOL_MIN_SIZE, DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN, INSTANCE_REFRESH_DEFAULT_MAX_HEALTHY, INSTANCE_REFRESH_DEFAULT_MIN_HEALTHY, INSTANCE_REFRESH_PDV_MAX_HEALTHY, INSTANCE_REFRESH_PDV_MIN_HEALTHY, inferAmiHardwareType } from "./ecsConstants.js";
 /**
  * Every `Ec2CapacityConfig` field, classified. The `Record<keyof …, …>`
  * satisfies-shape is a compile-time exhaustiveness guard in compiled `src/`
@@ -40,8 +40,7 @@ const OPAQUE_ASG_FIELDS = fieldsWithRole("property:opaque");
 /** The `"ARM" | "STANDARD"` label the config key and drift compare share. */
 function resolvedAmiHardwareLabel(config) {
     return (config.amiHardwareType ??
-        (inferAmiHardwareType(config.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE) ===
-            AmiHardwareType.ARM
+        (inferAmiHardwareType(config.instanceType ?? DEFAULT_ECS_EC2_INSTANCE_TYPE) === AmiHardwareType.ARM
             ? "ARM"
             : "STANDARD"));
 }
@@ -54,7 +53,7 @@ function resolvedAmiHardwareLabel(config) {
  * default (`desiredCapacity`, `associatePublicIpAddress`) compare raw.
  */
 const SCALAR_ASG_FIELD_RESOLVERS = {
-    instanceType: (c) => c.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE,
+    instanceType: (c) => c.instanceType ?? DEFAULT_ECS_EC2_INSTANCE_TYPE,
     amiHardwareType: resolvedAmiHardwareLabel,
     minCapacity: (c) => c.minCapacity ?? DEFAULT_EC2_MIN_CAPACITY,
     maxCapacity: (c) => c.maxCapacity ?? DEFAULT_EC2_MAX_CAPACITY,
@@ -246,6 +245,11 @@ export const LEGACY_KEY_FIELDS = [
     "persistentDataVolume",
     "availabilityZones"
 ];
+// The ECS EC2 instance-type default as it stood when the pre-6.0 legacy key
+// format was live. FROZEN: the legacy checksum must keep matching what
+// deployed pre-6.0 stacks derived, so it must not follow
+// DEFAULT_ECS_EC2_INSTANCE_TYPE.
+const LEGACY_KEY_DEFAULT_INSTANCE_TYPE = "t4g.micro";
 /**
  * The pre-6.0 config-derived identity key. SURVIVES ONLY as the legacy
  * checksum behind manifest identity-alias hints (`legacyKey`/`legacyAnchor`)
@@ -253,7 +257,7 @@ export const LEGACY_KEY_FIELDS = [
  * ASG sharing keys on the capacity SLOT.
  */
 export function getEc2ConfigKey(ec2Config) {
-    const instanceType = ec2Config.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE;
+    const instanceType = ec2Config.instanceType ?? LEGACY_KEY_DEFAULT_INSTANCE_TYPE;
     const amiHardwareType = resolvedAmiHardwareLabel(ec2Config);
     const warmPoolKey = ec2Config.warmPool
         ? `wp${ec2Config.warmPool.minSize ?? DEFAULT_WARM_POOL_MIN_SIZE}-${ec2Config.warmPool.reuseOnScaleIn ?? DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN}`

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

@@ -2,6 +2,7 @@ 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";
+export declare const DEFAULT_ECS_EC2_INSTANCE_TYPE = "t4g.small";
 export declare const DEFAULT_WARM_POOL_MIN_SIZE = 1;
 export declare const DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN = false;
 export declare const DEFAULT_LOG_RETENTION_DAYS = 14;
@@ -75,3 +76,26 @@ export declare const ARM_INSTANCE_PREFIXES: string[];
  * @returns AmiHardwareType.ARM for Graviton instances, AmiHardwareType.STANDARD for Intel/AMD
  */
 export declare function inferAmiHardwareType(instanceType: string): AmiHardwareType;
+/**
+ * The nominal (advertised) memory of an EC2 instance type, or `undefined` when
+ * the family or size is outside the allow-list (metal sizes, network variants,
+ * free-form strings) — callers MUST treat `undefined` as "cannot judge" and
+ * skip, never as zero.
+ *
+ * Nominal is an upper bound on what ECS can place against: the agent, kernel
+ * and system reserve consume a slice before the instance registers with the
+ * cluster (a t4g.medium registers 3835 of its nominal 4096 — the measured
+ * ground truth from the 2026-08-12 deploy-worker wedge). So a task demand
+ * `>= nominal` can NEVER be placed, and {@link estimatedEc2MemoryReserveMiB}
+ * approximates the slice for the near-miss warning band.
+ */
+export declare function nominalEc2InstanceMemoryMiB(instanceType: string): number | undefined;
+/**
+ * Estimated MiB the ECS agent + OS reserve consume before an instance
+ * registers its memory with the cluster. 6.5% is calibrated on the one
+ * measured point we own (t4g.medium: 4096 nominal − 3835 registered = 261,
+ * 6.4%), rounded up because under-estimating the reserve turns the warning
+ * band into a false pass; the 128 floor covers the smallest sizes where a
+ * percentage underestimates the fixed kernel cost.
+ */
+export declare function estimatedEc2MemoryReserveMiB(nominalMiB: number): number;

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

@@ -1,8 +1,16 @@
 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
+// Canonical source: @fjall/generator schemas/constants.ts — keep in sync.
+// Standalone EC2 instances (the compute:ec2 pattern) only; ECS EC2 capacity
+// defaults to DEFAULT_ECS_EC2_INSTANCE_TYPE below.
 export const DEFAULT_EC2_INSTANCE_TYPE = "t4g.micro";
+// Smallest type whose usable memory (nominal 2048 minus the agent/OS reserve)
+// fits the default container hard limit (1024) plus the schema-gate sidecar
+// (512). A t4g.micro registers under 1024 with ECS, so a micro default made
+// every defaults-only EC2 service structurally unplaceable — the same class
+// as the 2026-08-12 deploy-worker wedge, present from first deploy.
+export const DEFAULT_ECS_EC2_INSTANCE_TYPE = "t4g.small";
 export const DEFAULT_WARM_POOL_MIN_SIZE = 1;
 // reuseOnScaleIn: true returns scaled-in instances to the warm pool Stopped,
 // which can strand ECS tasks DRAINING indefinitely (the 2026-06-04 outage).
@@ -130,3 +138,103 @@ export function inferAmiHardwareType(instanceType) {
         ? AmiHardwareType.ARM
         : AmiHardwareType.STANDARD;
 }
+/**
+ * Nominal (advertised) memory at the `.medium` size for the EC2 families the
+ * memory-fit guard recognises. Sizes scale linearly from this base (nano ×1/8,
+ * micro ×1/4, small ×1/2, medium ×1, large ×2, xlarge ×4, Nxlarge ×4N), so one
+ * number per family covers the whole size ladder.
+ *
+ * Deliberately an allow-list, not a parser: network/local-NVMe variants
+ * (c5n, c6gn, m5zn, …) and exotic families carry different memory-per-size
+ * ratios, and a wrong nominal would turn the fit guard's verdict into a false
+ * rejection or a false pass. Unknown families make the guard skip instead —
+ * add a family here only with its ratio verified against the EC2 sizing table.
+ */
+const EC2_FAMILY_MEDIUM_MEMORY_MIB = {
+    // 4 GiB at .medium — burstable and general-purpose
+    t2: 4096,
+    t3: 4096,
+    t3a: 4096,
+    t4g: 4096,
+    m5: 4096,
+    m5a: 4096,
+    m6g: 4096,
+    m6gd: 4096,
+    m6i: 4096,
+    m7g: 4096,
+    m7gd: 4096,
+    m7i: 4096,
+    m8g: 4096,
+    m8gd: 4096,
+    // 2 GiB at .medium — compute-optimised
+    c5: 2048,
+    c6g: 2048,
+    c6gd: 2048,
+    c6i: 2048,
+    c7g: 2048,
+    c7gd: 2048,
+    c7i: 2048,
+    c8g: 2048,
+    c8gd: 2048,
+    // 8 GiB at .medium — memory-optimised
+    r5: 8192,
+    r6g: 8192,
+    r6gd: 8192,
+    r6i: 8192,
+    r7g: 8192,
+    r7gd: 8192,
+    r8g: 8192,
+    r8gd: 8192
+};
+const EC2_SIZE_MEMORY_MULTIPLIER = {
+    nano: 0.125,
+    micro: 0.25,
+    small: 0.5,
+    medium: 1,
+    large: 2,
+    xlarge: 4
+};
+/**
+ * The nominal (advertised) memory of an EC2 instance type, or `undefined` when
+ * the family or size is outside the allow-list (metal sizes, network variants,
+ * free-form strings) — callers MUST treat `undefined` as "cannot judge" and
+ * skip, never as zero.
+ *
+ * Nominal is an upper bound on what ECS can place against: the agent, kernel
+ * and system reserve consume a slice before the instance registers with the
+ * cluster (a t4g.medium registers 3835 of its nominal 4096 — the measured
+ * ground truth from the 2026-08-12 deploy-worker wedge). So a task demand
+ * `>= nominal` can NEVER be placed, and {@link estimatedEc2MemoryReserveMiB}
+ * approximates the slice for the near-miss warning band.
+ */
+export function nominalEc2InstanceMemoryMiB(instanceType) {
+    const parts = instanceType.split(".");
+    if (parts.length !== 2)
+        return undefined;
+    const family = parts[0];
+    const size = parts[1];
+    if (family === undefined || size === undefined)
+        return undefined;
+    const mediumMemoryMiB = EC2_FAMILY_MEDIUM_MEMORY_MIB[family];
+    if (mediumMemoryMiB === undefined)
+        return undefined;
+    const fixedMultiplier = EC2_SIZE_MEMORY_MULTIPLIER[size];
+    if (fixedMultiplier !== undefined)
+        return mediumMemoryMiB * fixedMultiplier;
+    const scaledSize = /^(\d+)xlarge$/.exec(size);
+    if (scaledSize?.[1] !== undefined) {
+        return mediumMemoryMiB * 4 * parseInt(scaledSize[1], 10);
+    }
+    return undefined;
+}
+/**
+ * Estimated MiB the ECS agent + OS reserve consume before an instance
+ * registers its memory with the cluster. 6.5% is calibrated on the one
+ * measured point we own (t4g.medium: 4096 nominal − 3835 registered = 261,
+ * 6.4%), rounded up because under-estimating the reserve turns the warning
+ * band into a false pass; the 128 floor covers the smallest sizes where a
+ * percentage underestimates the fixed kernel cost.
+ */
+export function estimatedEc2MemoryReserveMiB(nominalMiB) {
+    return Math.max(128, Math.ceil(nominalMiB * 0.065));
+}

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

@@ -11,7 +11,7 @@ import { Ec2Instance } from "./ec2.js";
 import { vpcHasNatGateways } from "../../../utils/vpcUtils.js";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
 import { stackScopedExportName } from "../../../utils/exportNaming.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 { DEFAULT_ECS_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 { assertAnchorUnique, assertSharedAsgConfigMatches, assertValidCapacitySlot, getEc2ConfigKey, legacyAnchorFromKey, LEGACY_KEY_FIELDS, resolveCapacityAnchor, resolveCapacitySlot } from "./ecsCapacityConfig.js";
 import { lookupCapacityIdentityPin } from "../../../utils/capacityIdentityContext.js";
 import { getCurrentCollector } from "../../../utils/manifestWriter.js";
@@ -114,7 +114,7 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
             legacyKeyFields: [...LEGACY_KEY_FIELDS]
         });
     }
-    const instanceType = ec2Config.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE;
+    const instanceType = ec2Config.instanceType ?? DEFAULT_ECS_EC2_INSTANCE_TYPE;
     const amiHardwareType = ec2Config.amiHardwareType
         ? ec2Config.amiHardwareType === "STANDARD"
             ? AmiHardwareType.STANDARD

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

@@ -114,7 +114,7 @@ export interface Ec2CapacityConfig {
      * should rely on the slot derivation.
      */
     identityAnchor?: string;
-    /** EC2 instance type. Default: "t4g.micro" */
+    /** EC2 instance type. Default: "t4g.small" */
     instanceType?: string;
     /** AMI hardware type. Default: "ARM" (Graviton - better cost/performance) */
     amiHardwareType?: "ARM" | "STANDARD";

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

@@ -1,3 +1,4 @@
+import type { IConstruct } from "constructs";
 import type { DomainConfig, EcsCapacityProvider, EcsClusterProps } from "./ecsTypes.js";
 /**
  * Validates ECS cluster props before construction.
@@ -26,9 +27,14 @@ import type { DomainConfig, EcsCapacityProvider, EcsClusterProps } from "./ecsTy
  * cannot pass it and there is no resources-layer code path to validate.
  *
  * @param props - The cluster props to validate
+ * @param annotationsScope - When provided (the `EcsCluster` constructor passes
+ *   `this`), non-fatal findings from {@link validateEc2TaskMemoryFit} are
+ *   emitted as CDK synth warnings; without a scope (pure validation contexts:
+ *   the contract corpus, unit tests) warnings are dropped and only throws
+ *   surface
  * @throws Error if validation fails
  */
-export declare function validateEcsClusterProps(props: EcsClusterProps): void;
+export declare function validateEcsClusterProps(props: EcsClusterProps, annotationsScope?: IConstruct): void;
 /**
  * Minimal structural input for {@link validateEc2ServiceSizing} — exactly the
  * fields the guard reads. Both the resources-layer `EcsServiceProps` and the
@@ -83,6 +89,67 @@ interface Ec2ServiceSizingInput {
  *   `ec2Config.memoryLimitMiB`
  */
 export declare function validateEc2ServiceSizing(service: Ec2ServiceSizingInput): void;
+/**
+ * Minimal structural input for {@link validateEc2TaskMemoryFit} — the fields
+ * the guard reads and nothing wider, so the resources-layer `EcsServiceProps`
+ * and the patterns-layer `EcsServiceConfig` both satisfy it (same seam
+ * discipline as {@link validateEc2ServiceSizing} above).
+ */
+interface Ec2MemoryFitInput {
+    name: string;
+    capacityProvider?: EcsCapacityProvider;
+    containers?: ReadonlyArray<{
+        name?: string;
+    }>;
+    ec2Config?: {
+        instanceType?: string;
+        memoryLimitMiB?: number;
+    };
+}
+/**
+ * Rejects an EC2 service whose task can never be PLACED: on the EC2 launch
+ * type every container carries a hard memory limit (the gate container gets
+ * {@link SCHEMA_GATE_CONTAINER_MEMORY_MIB}, every other container gets
+ * `ec2Config.memoryLimitMiB ?? DEFAULT_EC2_CONTAINER_MEMORY_MIB` — see
+ * `addContainersToTask` in `ecsTaskDefinition.ts`, whose derivation this guard
+ * mirrors), and ECS places a task only if the SUM of those limits fits the
+ * instance's registered memory. Registered memory is always strictly below the
+ * type's nominal memory (agent + OS reserve), so a demand `>= nominal` is
+ * structurally unplaceable on ANY instance count — the stack deploys cleanly
+ * while desiredCount is 0, then wedges at the first scale-up. That is the
+ * 2026-08-12 production wedge (deploy-worker 2048 + gate 2048 = 4096 demanded
+ * of a t4g.medium's 3835 registered), which this guard converts into a synth
+ * error.
+ *
+ * Two verdicts:
+ *
+ * - demand >= nominal → THROW. Zero false positives by construction:
+ *   registered < nominal always, so nothing that deploys today can trip it.
+ *   Applies equally to the defaulted instance type
+ *   ({@link DEFAULT_ECS_EC2_INSTANCE_TYPE}) — the defaults combo (t4g.small +
+ *   1024, or + the gate's 512) fits with headroom, so an oversubscribed bare
+ *   `ec2Config: {}` means the caller added containers without sizing and the
+ *   task is just as unplaceable as an explicitly-sized one.
+ * - demand > nominal − {@link estimatedEc2MemoryReserveMiB} → WARNING. The
+ *   demand fits nominal but sits inside the estimated agent/OS reserve band,
+ *   where placement depends on the AMI's exact registered memory.
+ *
+ * Skips (returns no findings) for Fargate services and for instance types
+ * outside the `nominalEc2InstanceMemoryMiB` allow-list.
+ *
+ * Called from BOTH validation layers, like {@link validateEc2ServiceSizing}:
+ * patterns `validateEcsProps` (throw-only — at that layer the gate container
+ * is not yet injected, so its demand under-counts by the gate's 512 MiB and
+ * warnings would be premature) and resources `validateEcsClusterProps` (the
+ * containers list is final there — gate and migration containers included —
+ * so both throws and warnings are exact).
+ *
+ * @param service - The service props to validate (no-op unless EC2 capacity)
+ * @returns Warning messages for the non-fatal verdicts (caller decides the
+ *   sink — `validateEcsClusterProps` emits them as CDK synth warnings)
+ * @throws Error when the task demand cannot fit the explicitly chosen sizing
+ */
+export declare function validateEc2TaskMemoryFit(service: Ec2MemoryFitInput): string[];
 /**
  * Domain-config constraints shared by the resources-layer hook
  * (`validateEcsClusterProps`) and the patterns-layer mirror

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

@@ -1,8 +1,10 @@
+import { Annotations } from "aws-cdk-lib";
 import { NetworkMode } from "aws-cdk-lib/aws-ecs";
 import { evaluateBakeGuard } from "@fjall/util/docker";
+import { SCHEMA_GATE_CONTAINER_NAME } from "@fjall/util/migration";
 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 { DEFAULT_EC2_CONTAINER_MEMORY_MIB, DEFAULT_ECS_EC2_INSTANCE_TYPE, SCHEMA_GATE_CONTAINER_MEMORY_MIB, estimatedEc2MemoryReserveMiB, nominalEc2InstanceMemoryMiB, resolveEc2ContainerMemoryMiB } from "./ecsConstants.js";
 import { validateSharedEc2CapacityConfig } from "./ecsCapacityConfig.js";
 /**
  * Validates ECS cluster props before construction.
@@ -31,9 +33,14 @@ import { validateSharedEc2CapacityConfig } from "./ecsCapacityConfig.js";
  * cannot pass it and there is no resources-layer code path to validate.
  *
  * @param props - The cluster props to validate
+ * @param annotationsScope - When provided (the `EcsCluster` constructor passes
+ *   `this`), non-fatal findings from {@link validateEc2TaskMemoryFit} are
+ *   emitted as CDK synth warnings; without a scope (pure validation contexts:
+ *   the contract corpus, unit tests) warnings are dropped and only throws
+ *   surface
  * @throws Error if validation fails
  */
-export function validateEcsClusterProps(props) {
+export function validateEcsClusterProps(props, annotationsScope) {
     validateEcsDomainConfig(props.cluster?.domainConfig, props.clusterName);
     const loadBalancerDisabled = props.cluster?.loadBalancer === false ||
         props.cluster?.directAccess === true;
@@ -130,6 +137,12 @@ export function validateEcsClusterProps(props) {
                 "Provide ec2Config on the service.");
         }
         validateEc2ServiceSizing(service);
+        const memoryFitWarnings = validateEc2TaskMemoryFit(service);
+        if (annotationsScope !== undefined) {
+            for (const warning of memoryFitWarnings) {
+                Annotations.of(annotationsScope).addWarningV2("@fjall/components-infrastructure:ec2TaskMemoryFit", warning);
+            }
+        }
         if (typeof service.circuitBreaker === "object") {
             const threshold = service.circuitBreaker.threshold;
             if (threshold !== undefined &&
@@ -280,6 +293,96 @@ export function validateEc2ServiceSizing(service) {
             "(Service-level cpu only applies to Fargate services.)");
     }
 }
+/**
+ * Rejects an EC2 service whose task can never be PLACED: on the EC2 launch
+ * type every container carries a hard memory limit (the gate container gets
+ * {@link SCHEMA_GATE_CONTAINER_MEMORY_MIB}, every other container gets
+ * `ec2Config.memoryLimitMiB ?? DEFAULT_EC2_CONTAINER_MEMORY_MIB` — see
+ * `addContainersToTask` in `ecsTaskDefinition.ts`, whose derivation this guard
+ * mirrors), and ECS places a task only if the SUM of those limits fits the
+ * instance's registered memory. Registered memory is always strictly below the
+ * type's nominal memory (agent + OS reserve), so a demand `>= nominal` is
+ * structurally unplaceable on ANY instance count — the stack deploys cleanly
+ * while desiredCount is 0, then wedges at the first scale-up. That is the
+ * 2026-08-12 production wedge (deploy-worker 2048 + gate 2048 = 4096 demanded
+ * of a t4g.medium's 3835 registered), which this guard converts into a synth
+ * error.
+ *
+ * Two verdicts:
+ *
+ * - demand >= nominal → THROW. Zero false positives by construction:
+ *   registered < nominal always, so nothing that deploys today can trip it.
+ *   Applies equally to the defaulted instance type
+ *   ({@link DEFAULT_ECS_EC2_INSTANCE_TYPE}) — the defaults combo (t4g.small +
+ *   1024, or + the gate's 512) fits with headroom, so an oversubscribed bare
+ *   `ec2Config: {}` means the caller added containers without sizing and the
+ *   task is just as unplaceable as an explicitly-sized one.
+ * - demand > nominal − {@link estimatedEc2MemoryReserveMiB} → WARNING. The
+ *   demand fits nominal but sits inside the estimated agent/OS reserve band,
+ *   where placement depends on the AMI's exact registered memory.
+ *
+ * Skips (returns no findings) for Fargate services and for instance types
+ * outside the `nominalEc2InstanceMemoryMiB` allow-list.
+ *
+ * Called from BOTH validation layers, like {@link validateEc2ServiceSizing}:
+ * patterns `validateEcsProps` (throw-only — at that layer the gate container
+ * is not yet injected, so its demand under-counts by the gate's 512 MiB and
+ * warnings would be premature) and resources `validateEcsClusterProps` (the
+ * containers list is final there — gate and migration containers included —
+ * so both throws and warnings are exact).
+ *
+ * @param service - The service props to validate (no-op unless EC2 capacity)
+ * @returns Warning messages for the non-fatal verdicts (caller decides the
+ *   sink — `validateEcsClusterProps` emits them as CDK synth warnings)
+ * @throws Error when the task demand cannot fit the explicitly chosen sizing
+ */
+export function validateEc2TaskMemoryFit(service) {
+    if (service.capacityProvider !== "EC2")
+        return [];
+    const instanceTypeIsDefaulted = service.ec2Config?.instanceType === undefined;
+    const instanceType = service.ec2Config?.instanceType ?? DEFAULT_ECS_EC2_INSTANCE_TYPE;
+    const nominal = nominalEc2InstanceMemoryMiB(instanceType);
+    if (nominal === undefined)
+        return [];
+    const perContainerMemory = resolveEc2ContainerMemoryMiB(service.ec2Config);
+    const containers = service.containers !== undefined && service.containers.length > 0
+        ? service.containers
+        : [{ name: service.name }];
+    const accounting = [];
+    let demand = 0;
+    for (const container of containers) {
+        const memory = container.name === SCHEMA_GATE_CONTAINER_NAME
+            ? SCHEMA_GATE_CONTAINER_MEMORY_MIB
+            : perContainerMemory;
+        demand += memory;
+        accounting.push(`${container.name ?? "(default)"}=${memory}`);
+    }
+    const reserve = estimatedEc2MemoryReserveMiB(nominal);
+    const instanceTypeLabel = instanceTypeIsDefaulted
+        ? `${instanceType} (the ECS EC2 default)`
+        : instanceType;
+    if (demand >= nominal) {
+        throw new Error(`Service '${service.name}': container hard memory limits total ${demand} MiB ` +
+            `(${accounting.join(" + ")}), which cannot fit a ${instanceTypeLabel} — ECS ` +
+            `registers less than the nominal ${nominal} MiB per instance (the ECS agent ` +
+            `and OS reserve roughly ${reserve} MiB), so no task of this shape can ever ` +
+            `be placed, on any instance count. The stack deploys cleanly while ` +
+            `desiredCount is 0, then wedges at the first scale-up. Lower ` +
+            `ec2Config.memoryLimitMiB (every app container takes that hard limit), ` +
+            `choose a larger ec2Config.instanceType, or run fewer containers in the task.`);
+    }
+    if (demand > nominal - reserve) {
+        return [
+            `Service '${service.name}': container hard memory limits total ${demand} MiB ` +
+                `of a ${instanceTypeLabel}'s nominal ${nominal} MiB — inside the ECS agent/OS ` +
+                `reserve band (estimated usable ~${nominal - reserve} MiB). Placement can ` +
+                `fail depending on the AMI's exact registered memory. Leave ~${reserve} MiB ` +
+                `headroom: lower ec2Config.memoryLimitMiB or choose a larger ` +
+                `ec2Config.instanceType.`
+        ];
+    }
+    return [];
+}
 /**
  * Domain-config constraints shared by the resources-layer hook
  * (`validateEcsClusterProps`) and the patterns-layer mirror