@fjall/components-infrastructure 4.4.0 → 5.0.0

package/dist/lib/config/aws/oidcConnector.d.ts

@@ -24,12 +24,12 @@ export interface OidcConnectorProps {
      * Account TIER of the connected account (organisation | platform | account) —
      * the structural TIER axis, from the account stack's polymorphic
      * `deployRoleAccountTier()`; NEVER the wire `environment` / stage axis (that is
-     * `accountStage`). Drives the §4.4a deploy-trust governance expand: a
-     * governance tier (organisation/platform) plus the synth account id widens the
-     * `FjallDeploy` machine subject to ALSO accept the account-scoped literal
-     * `org:{orgId}:acct:{awsAccountId}` (StringEquals array = OR of exact
-     * literals), so per-account deploy issuance can later flip. App-tier
-     * ("account") or absent ⇒ generic-only scalar (unchanged, fail-safe).
+     * `accountStage`). Since the §4.4b Step-1 expand, trust WIDTH no longer
+     * keys on this tier: every synth passes the account id, so the `FjallDeploy`
+     * machine subject accepts `[generic, acct]` (StringEquals array = OR of
+     * exact literals) for EVERY tier, letting per-account deploy issuance flip.
+     * The tier now gates only the `machineTrustMode: "account-scoped"` contract
+     * (governance-only until §4.4b's probe gate) and the boundary preset.
      */
     accountTier?: AccountTier;
     /**

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

@@ -61,16 +61,17 @@ export declare class Account extends Stack {
      */
     protected receivesDeployRole(): boolean;
     /**
-     * Account TIER passed to this account's `OidcConnector` for the §4.4a
-     * deploy-trust governance expand. A polymorphic METHOD, not a read of the
-     * `organisationType` field: the connector is instantiated in THIS base
-     * constructor, and subclass field initialisers run AFTER `super()`, so
-     * `this.organisationType` would read "account" for every subclass here (the
-     * same construction-order reason `receivesDeployRole()` is a method). Base ⇒
-     * "account" (app-tier, generic-only trust); `Platform` ⇒ "platform" and
-     * `Organisation` ⇒ "organisation" override. Governance tiers widen the deploy
-     * machine subject; kept in lockstep with `organisationType` by the
-     * Platform-synth deploy-trust parity test.
+     * Account TIER passed to this account's `OidcConnector`. A polymorphic
+     * METHOD, not a read of the `organisationType` field: the connector is
+     * instantiated in THIS base constructor, and subclass field initialisers run
+     * AFTER `super()`, so `this.organisationType` would read "account" for every
+     * subclass here (the same construction-order reason `receivesDeployRole()`
+     * is a method). Base ⇒ "account"; `Platform` ⇒ "platform" and `Organisation`
+     * ⇒ "organisation" override. Since the §4.4b Step-1 expand every tier
+     * renders the widened `[generic, acct]` machine subject — the tier now gates
+     * only the governance-only "account-scoped" contract mode (the builder
+     * throws for tier "account"); kept in lockstep with `organisationType` by
+     * the Platform-synth deploy-trust parity test.
      */
     protected deployRoleAccountTier(): AccountTier;
     /**

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

@@ -151,16 +151,17 @@ export class Account extends Stack {
         return this.constructor === Account;
     }
     /**
-     * Account TIER passed to this account's `OidcConnector` for the §4.4a
-     * deploy-trust governance expand. A polymorphic METHOD, not a read of the
-     * `organisationType` field: the connector is instantiated in THIS base
-     * constructor, and subclass field initialisers run AFTER `super()`, so
-     * `this.organisationType` would read "account" for every subclass here (the
-     * same construction-order reason `receivesDeployRole()` is a method). Base ⇒
-     * "account" (app-tier, generic-only trust); `Platform` ⇒ "platform" and
-     * `Organisation` ⇒ "organisation" override. Governance tiers widen the deploy
-     * machine subject; kept in lockstep with `organisationType` by the
-     * Platform-synth deploy-trust parity test.
+     * Account TIER passed to this account's `OidcConnector`. A polymorphic
+     * METHOD, not a read of the `organisationType` field: the connector is
+     * instantiated in THIS base constructor, and subclass field initialisers run
+     * AFTER `super()`, so `this.organisationType` would read "account" for every
+     * subclass here (the same construction-order reason `receivesDeployRole()`
+     * is a method). Base ⇒ "account"; `Platform` ⇒ "platform" and `Organisation`
+     * ⇒ "organisation" override. Since the §4.4b Step-1 expand every tier
+     * renders the widened `[generic, acct]` machine subject — the tier now gates
+     * only the governance-only "account-scoped" contract mode (the builder
+     * throws for tier "account"); kept in lockstep with `organisationType` by
+     * the Platform-synth deploy-trust parity test.
      */
     deployRoleAccountTier() {
         return "account";

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

@@ -17,9 +17,22 @@ export interface ClickHouseDatabaseProps {
     type: "ClickHouse";
     /** VPC to deploy into. Falls back to `app.getVpc()` via the factory. */
     vpc?: IVpc;
-    /** EC2 instance type. Default: `m7g.medium` (1 vCPU sustained, 4 GiB).
-     *  CH user-data is tuned for 1 vCPU; raise per-user `max_threads` and
-     *  `max_concurrent_queries` if bumping to a >=2 vCPU host. */
+    /** 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.
+     *
+     *  WARNING — changing this on a DEPLOYED stack REPLACES the persistent
+     *  data volume, not just the instance. The instance type is embedded in
+     *  the compute construct's logical-ID key (`getEc2ConfigKey`), so the
+     *  `AWS::EC2::Volume` beneath it gets a new logical ID: CloudFormation
+     *  snapshots-then-deletes the old volume (`RemovalPolicy.SNAPSHOT`) and
+     *  creates an EMPTY one, and the volume's `ownerLogicalId` re-attach tag
+     *  chain resets. Plan a snapshot-restore migration for live data — this
+     *  is NOT a config-only change on a stack with data. */
     instanceType?: string;
     /**
      * ECS service desired task count. Defaults to 1 (single-node, single-task

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

@@ -22,7 +22,7 @@ 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 { 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, CLICKHOUSE_TASK_MEMORY_MIB, 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, 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, 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";
 /**
@@ -375,6 +375,10 @@ export class ClickHouseDatabase extends Construct {
                     name: "ClickHouseService",
                     capacityProvider: "EC2",
                     desiredCount,
+                    // Omitting `scaling` attaches default CPU target tracking. A scaled-out
+                    // second task is an EMPTY second database behind the same Cloud Map name
+                    // (plain MergeTree does not replicate) — desired-count scaling stays off.
+                    scaling: false,
                     serviceDiscovery: {
                         name: CLICKHOUSE_CLOUDMAP_SERVICE_NAME,
                         // getaddrinfo clients require A; AWS rejects A under HOST/BRIDGE → AWS_VPC.
@@ -403,7 +407,7 @@ export class ClickHouseDatabase extends Construct {
                         desiredCapacity: 1,
                         minCapacity: 1,
                         maxCapacity: 1,
-                        memoryLimitMiB: CLICKHOUSE_TASK_MEMORY_MIB,
+                        memoryLimitMiB: clickHouseTaskMemoryMiB(instanceType),
                         tags: {
                             [CLICKHOUSE_SERVER_ROLE_TAG.key]: CLICKHOUSE_SERVER_ROLE_TAG.value
                         }
@@ -493,6 +497,23 @@ export class ClickHouseDatabase extends Construct {
             tlsCaSecret.grantRead(instanceRole);
         if (tlsServerSecret !== undefined)
             tlsServerSecret.grantRead(instanceRole);
+        // For the user-data host-metrics timer (see buildClickHouseUserData).
+        // PutMetricData is not resource-scopable; the namespace condition bounds
+        // the grant to the CWAgent metrics the host alarms consume. The describe
+        // grant backs the IMDS-tag fallback path for ASG-name resolution.
+        instanceRole.addToPrincipalPolicy(new PolicyStatement({
+            actions: ["cloudwatch:PutMetricData"],
+            resources: ["*"],
+            conditions: {
+                StringEquals: {
+                    "cloudwatch:namespace": CLICKHOUSE_HOST_METRICS.namespace
+                }
+            }
+        }));
+        instanceRole.addToPrincipalPolicy(new PolicyStatement({
+            actions: ["autoscaling:DescribeAutoScalingInstances"],
+            resources: ["*"]
+        }));
         // asgName is the CloudWatch dimension the host metrics key off, so without
         // it the alarms cannot be built; no topic is the default, so skip silently
         // rather than throw.

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

@@ -622,9 +622,19 @@ export interface EcsServiceConfig {
      * ]
      */
     routing?: EcsRoutingConfig | EcsRoutingConfig[];
-    /** CPU units for this service's tasks (256-4096) */
+    /**
+     * CPU units for this service's tasks (256-4096). Fargate only — EC2 task
+     * definitions carry no task-level CPU reservation (CPU is bounded by the
+     * instance type), so a value here is rejected at synth when `capacityProvider`
+     * is 'EC2' (see `validateEc2ServiceSizing`).
+     */
     cpu?: number;
-    /** Memory in MiB for this service's tasks (512-30720) */
+    /**
+     * Memory in MiB for this service's tasks (512-30720). Fargate only — for EC2
+     * capacity the container memory comes from `ec2Config.memoryLimitMiB`; a
+     * service-level value here is rejected at synth unless it exactly mirrors
+     * that field (see `validateEc2ServiceSizing`).
+     */
     memoryLimitMiB?: number;
     /** Desired number of tasks. Default: 2 */
     desiredCount?: number;

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

@@ -16,15 +16,15 @@ import { Duration } from "aws-cdk-lib";
 export { isAwsManagedKey, isCMKRequested, AWS_MANAGED, USE_CMK } from "../../utils/databaseTypes.js";
 export const DATABASE_ENGINE_CONFIG = Object.freeze({
     postgresql: {
-        aurora: { version: "16.10", majorVersion: "16" },
-        instance: { version: "17.5", majorVersion: "17" },
+        aurora: { version: "18.4", majorVersion: "18" },
+        instance: { version: "17.9", majorVersion: "17" },
         defaultUsername: "postgres",
         sslParameters: { "rds.force_ssl": "1" }
     },
     mysql: {
-        // majorVersion must be Aurora version (3.08.0), NOT MySQL version (8.0)
-        aurora: { version: "8.0.mysql_aurora.3.08.0", majorVersion: "3.08.0" },
-        instance: { version: "8.4.4", majorVersion: "8.4" },
+        // majorVersion must be Aurora version (3.12.0), NOT MySQL version (8.0)
+        aurora: { version: "8.0.mysql_aurora.3.12.0", majorVersion: "3.12.0" },
+        instance: { version: "8.4.9", majorVersion: "8.4" },
         defaultUsername: "admin",
         sslParameters: { require_secure_transport: "ON" }
     }

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

@@ -66,6 +66,7 @@ export default class EcsCluster extends Construct {
     // EC2-specific (mutable state shared with ecsServiceFactory)
     asgState = {
         providers: new Map(),
+        asgOrigins: new Map(),
         autoScalingGroup: undefined,
         asgSecurityGroup: undefined
     };

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

@@ -8,6 +8,20 @@ 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;
+/**
+ * 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

@@ -16,6 +16,20 @@ 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;
+/**
+ * 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 +60,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/ecsServiceFactory.d.ts

@@ -17,6 +17,15 @@ 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, {
+        serviceName: string;
+        ec2Config: Ec2CapacityConfig;
+    }>;
     autoScalingGroup?: AutoScalingGroup;
     asgSecurityGroup?: ISecurityGroup;
 }

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

@@ -26,6 +26,67 @@ export function resolveCircuitBreaker(config) {
     const rollback = config?.rollback ?? true;
     return { enable: true, rollback };
 }
+/**
+ * `ec2Config` fields that shape the ASG but are NOT part of
+ * {@link getEc2ConfigKey}, split by how a difference can be detected without
+ * false positives. A second service whose key matches reuses the first
+ * service's ASG, so any of these it sets is silently discarded.
+ *
+ * Scalars compare by value. `tags` is plain data, so it compares deeply.
+ * `machineImage` / `userData` / `blockDevices` are CDK objects with no stable
+ * structural identity — two equivalent literals are different references, so
+ * only a defined-vs-undefined asymmetry is safe to report. They deliberately
+ * under-report: over-reporting is a hard synth failure on config that
+ * previously worked, which is the more damaging direction.
+ */
+const SCALAR_ASG_FIELDS = [
+    "minCapacity",
+    "maxCapacity",
+    "desiredCapacity",
+    "instanceMonitoring",
+    "associatePublicIpAddress"
+];
+const OPAQUE_ASG_FIELDS = [
+    "machineImage",
+    "userData",
+    "blockDevices"
+];
+function tagRecordsEqual(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    const aKeys = Object.keys(a);
+    if (aKeys.length !== Object.keys(b).length)
+        return false;
+    return aKeys.every((key) => Object.is(a[key], b[key]));
+}
+function findDifferingAsgFields(ec2Config, origin) {
+    const differing = SCALAR_ASG_FIELDS.filter((field) => !Object.is(ec2Config[field], 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 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`).
+ */
+function assertSharedAsgConfigMatches(serviceName, ec2Config, key, origin) {
+    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 ('instanceType', 'amiHardwareType', 'warmPool', ` +
+        `'persistentDataVolume', 'availabilityZones').`);
+}
 /**
  * Generates a unique key for EC2 config so services with matching
  * configurations share an ASG.
@@ -71,8 +132,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
@@ -160,7 +226,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

@@ -156,12 +156,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) {

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;