@fjall/components-infrastructure 10.1.2 → 11.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/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/ecsConstants.d.ts

@@ -41,6 +41,19 @@ export declare const DEFAULT_ROLLING_UPDATE_PAUSE_SECONDS = 300;
 export declare function resolveEc2ContainerMemoryMiB(ec2Config: {
     readonly memoryLimitMiB?: number;
 } | undefined): number;
+/**
+ * Hard memory limit for the synthetic `fjall-schema-gate` container on
+ * EC2-capacity services. The gate is a run-to-completion Node probe (a
+ * handful of DB queries, then exit) — giving it the service's full
+ * `ec2Config.memoryLimitMiB` doubles the task's placement requirement and
+ * can exceed the instance's registered memory entirely: with the 2048 MiB
+ * deploy-worker limit the task demanded 4096 MiB against a t4g.medium's
+ * 3835, making every task structurally unplaceable (2026-08-12 production
+ * wedge — armed silently at desiredCount 0, detonated on the first
+ * queue-driven scale-up mid-CFN-update). Fargate services are unaffected:
+ * their memory is task-level, so the gate shares the task envelope.
+ */
+export declare const SCHEMA_GATE_CONTAINER_MEMORY_MIB = 512;
 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;
@@ -62,3 +75,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

@@ -54,6 +54,19 @@ export const DEFAULT_ROLLING_UPDATE_PAUSE_SECONDS = 300;
 export function resolveEc2ContainerMemoryMiB(ec2Config) {
     return ec2Config?.memoryLimitMiB ?? DEFAULT_EC2_CONTAINER_MEMORY_MIB;
 }
+/**
+ * Hard memory limit for the synthetic `fjall-schema-gate` container on
+ * EC2-capacity services. The gate is a run-to-completion Node probe (a
+ * handful of DB queries, then exit) — giving it the service's full
+ * `ec2Config.memoryLimitMiB` doubles the task's placement requirement and
+ * can exceed the instance's registered memory entirely: with the 2048 MiB
+ * deploy-worker limit the task demanded 4096 MiB against a t4g.medium's
+ * 3835, making every task structurally unplaceable (2026-08-12 production
+ * wedge — armed silently at desiredCount 0, detonated on the first
+ * queue-driven scale-up mid-CFN-update). Fargate services are unaffected:
+ * their memory is task-level, so the gate shares the task envelope.
+ */
+export const SCHEMA_GATE_CONTAINER_MEMORY_MIB = 512;
 // 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.
@@ -117,3 +130,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/ecsTaskDefinition.js

@@ -4,9 +4,10 @@ import { Secret as EcsSecret } from "aws-cdk-lib/aws-ecs";
 import { StringParameter } from "aws-cdk-lib/aws-ssm";
 import { buildParameterPath } from "@fjall/util";
 import { DEFAULT_ALB_IDLE_TIMEOUT_SECONDS, FJALL_ALB_IDLE_TIMEOUT_ENV_VAR } from "@fjall/util/httpKeepAlive";
+import { SCHEMA_GATE_CONTAINER_NAME } from "@fjall/util/migration";
 import { resolveOrgId } from "../../../utils/cdkContext.js";
 import { validateSsmPathComponent, validateSecretName } from "./ecsValidation.js";
-import { DEFAULT_LOG_RETENTION, DEFAULT_FARGATE_CPU, DEFAULT_FARGATE_MEMORY_MIB, resolveEc2ContainerMemoryMiB } from "./ecsConstants.js";
+import { DEFAULT_LOG_RETENTION, DEFAULT_FARGATE_CPU, DEFAULT_FARGATE_MEMORY_MIB, resolveEc2ContainerMemoryMiB, SCHEMA_GATE_CONTAINER_MEMORY_MIB } from "./ecsConstants.js";
 import { LogGroup } from "../logging/logGroup.js";
 import { getContainerImage } from "./ecsImages.js";
 import { resolveRemoteConnections } from "./ecsRemoteConnections.js";
@@ -230,8 +231,13 @@ export function addContainersToTask(ctx, serviceName, serviceProps, taskDefiniti
             startTimeout: containerConfig.startTimeout !== undefined
                 ? Duration.seconds(containerConfig.startTimeout)
                 : undefined,
+            // EC2 placement demands the SUM of container hard limits — the gate
+            // probe must not inherit the service's full per-container limit (see
+            // SCHEMA_GATE_CONTAINER_MEMORY_MIB; the gate name is synth-reserved).
             ...(isServiceEc2(serviceProps) && {
-                memoryLimitMiB: resolveEc2ContainerMemoryMiB(serviceProps.ec2Config)
+                memoryLimitMiB: containerConfig.name === SCHEMA_GATE_CONTAINER_NAME
+                    ? SCHEMA_GATE_CONTAINER_MEMORY_MIB
+                    : resolveEc2ContainerMemoryMiB(serviceProps.ec2Config)
             })
         });
         if (containerConfig.port !== undefined &&

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,68 @@ 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.
+ *
+ * Three verdicts:
+ *
+ * - demand >= nominal AND the sizing is explicit (`ec2Config.instanceType` or
+ *   `ec2Config.memoryLimitMiB` set) → THROW. Zero false positives by
+ *   construction: registered < nominal always, so nothing that deploys today
+ *   can trip it.
+ * - demand >= nominal on an all-defaults `ec2Config` → WARNING only. The
+ *   default instanceType/memory combo (t4g.micro + 1024) is itself
+ *   oversubscribed, so throwing would reject every bare `ec2Config: {}`
+ *   consumer; fixing the defaults is a separate decision.
+ * - 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_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,104 @@ 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.
+ *
+ * Three verdicts:
+ *
+ * - demand >= nominal AND the sizing is explicit (`ec2Config.instanceType` or
+ *   `ec2Config.memoryLimitMiB` set) → THROW. Zero false positives by
+ *   construction: registered < nominal always, so nothing that deploys today
+ *   can trip it.
+ * - demand >= nominal on an all-defaults `ec2Config` → WARNING only. The
+ *   default instanceType/memory combo (t4g.micro + 1024) is itself
+ *   oversubscribed, so throwing would reject every bare `ec2Config: {}`
+ *   consumer; fixing the defaults is a separate decision.
+ * - 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 instanceType = service.ec2Config?.instanceType ?? DEFAULT_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 explicitlySized = service.ec2Config?.instanceType !== undefined ||
+        service.ec2Config?.memoryLimitMiB !== undefined;
+    if (demand >= nominal) {
+        if (explicitlySized) {
+            throw new Error(`Service '${service.name}': container hard memory limits total ${demand} MiB ` +
+                `(${accounting.join(" + ")}), which cannot fit a ${instanceType} — 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.`);
+        }
+        return [
+            `Service '${service.name}': container hard memory limits total ${demand} MiB ` +
+                `(${accounting.join(" + ")}), which cannot fit the default ${instanceType} ` +
+                `(nominal ${nominal} MiB, less after the ECS agent/OS reserve) — no task of ` +
+                `this shape can be placed at runtime. Set ec2Config.instanceType to a ` +
+                `larger type or lower ec2Config.memoryLimitMiB.`
+        ];
+    }
+    if (demand > nominal - reserve) {
+        return [
+            `Service '${service.name}': container hard memory limits total ${demand} MiB ` +
+                `of a ${instanceType}'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

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

@@ -10,19 +10,17 @@ export declare const CLICKHOUSE_DATABASE_NAME = "analytics";
  *  of 2 vCPU) for the rest of the hour. Graviton3 is also ~25% faster on
  *  columnar scans than Graviton2.
  *
- *  Settings are tuned for 1 vCPU sustained (max_threads=1 across all profiles,
- *  max_concurrent_queries=8) — see clickhouseUserData.ts. Bumping to a larger
- *  instance MUST be paired with raising those thread/concurrency caps.
- *
  *  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. */
+ *  the container memory limit, server pools/caches, and profile resource
+ *  caps ALL derive from the type automatically (`clickHouseTaskMemoryMiB()`,
+ *  `deriveClickHouseServerTuning()`, `deriveClickHouseDefaultProfiles()`).
+ *  A size change needs no manual re-tune — but it DOES need an instance
+ *  refresh + server restart to take effect (config is baked into user-data). */
 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
@@ -62,8 +60,17 @@ export declare const CLICKHOUSE_HOST_RESERVE_MIB = 1024;
  *  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. */
+/** Hardware spec of every instance type the ClickHouse construct supports.
+ *  Values are the AWS nominal figures. Single source of truth for BOTH the
+ *  container memory limit (`clickHouseTaskMemoryMiB`) and the derived server
+ *  tuning + default profiles (`clickhouseTuning.ts`) — adding a type here is
+ *  the only step needed to support it end to end. */
+export interface ClickHouseInstanceSpec {
+    vcpus: number;
+    memoryGib: number;
+}
+export declare const CLICKHOUSE_INSTANCE_SPECS: Record<string, ClickHouseInstanceSpec>;
+/** Derived memory-only view of CLICKHOUSE_INSTANCE_SPECS. */
 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
@@ -197,6 +204,14 @@ export declare const CLICKHOUSE_CLOUDMAP_SERVICE_NAME = "clickhouse";
  *  live-reload path into a silent no-op without any compile/test signal,
  *  so this lives as a single source of truth. */
 export declare const CLICKHOUSE_SERVER_CONTAINER_NAME = "clickhouse";
+/** ECS service name for the ClickHouse server. Coupled cross-repo value:
+ *  the webapp log collector excludes this service from customer log
+ *  collection by exact name (`CLICKHOUSE_SERVER_SERVICE_NAME` at
+ *  `webapp/app/.server/services/monitoring/logGroupResolution.ts`) —
+ *  deliberately duplicated rather than shared, so a webapp deploy is never
+ *  release-coupled to a constructs mint. Renaming this service breaks that
+ *  exclusion silently; update both sites together. */
+export declare const CLICKHOUSE_SERVICE_NAME = "ClickHouseService";
 /** Materialised views that benefit from periodic OPTIMIZE to reduce part count at read time.
  *  These are not ReplacingMergeTree (no dedup needed) but un-merged parts force
  *  read-time aggregation which degrades query performance.