@fjall/components-infrastructure 4.4.0 → 5.0.0

package/dist/lib/resources/aws/database/clickhouseConstants.js

@@ -14,10 +14,15 @@ export 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 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,66 @@ export 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 const CLICKHOUSE_IMAGE = "docker.io/clickhouse/clickhouse-server:26.3.10.60";
+export const CLICKHOUSE_IMAGE = "docker.io/clickhouse/clickhouse-server:26.3.17.56";
 /** EBS volume configuration. */
 export const CLICKHOUSE_EBS_VOLUME_SIZE_GB = 80;
 export const CLICKHOUSE_EBS_IOPS = 3000;
 export 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 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 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 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 const CLICKHOUSE_INSTANCE_MEMORY_GIB = {
+    "t4g.medium": 4,
+    "m7g.medium": 4,
+    "m8g.medium": 4,
+    "r7g.medium": 8,
+    "r8g.medium": 8,
+    "m7g.large": 8,
+    "m8g.large": 8,
+    "r7g.large": 16,
+    "r8g.large": 16,
+    "m7g.xlarge": 16,
+    "m8g.xlarge": 16,
+    "r7g.xlarge": 32,
+    "r8g.xlarge": 32
+};
+/** 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 function clickHouseTaskMemoryMiB(instanceType) {
+    const memoryGib = CLICKHOUSE_INSTANCE_MEMORY_GIB[instanceType];
+    if (memoryGib === undefined) {
+        throw new Error(`ClickHouseDatabase: unknown instance type '${instanceType}' — cannot ` +
+            "derive the container memory limit. Supported: " +
+            `${Object.keys(CLICKHOUSE_INSTANCE_MEMORY_GIB).join(", ")}. Add the ` +
+            "type's nominal memory to CLICKHOUSE_INSTANCE_MEMORY_GIB " +
+            "(clickhouseConstants.ts) to support it.");
+    }
+    // ≥32 GiB rows double the reserve: the kernel-invisible gap (firmware +
+    // page structs) approaches 1 GiB there, and a limit above what the ECS
+    // agent advertises (MemTotal − ECS_RESERVED_MEMORY) strands the task in
+    // PROVISIONING with no CloudFormation error.
+    const reserveMib = memoryGib >= 32
+        ? CLICKHOUSE_HOST_RESERVE_MIB * 2
+        : CLICKHOUSE_HOST_RESERVE_MIB;
+    return memoryGib * 1024 - reserveMib;
+}
 /** ClickHouse ports. */
 export const CLICKHOUSE_HTTP_PORT = 8123;
 export const CLICKHOUSE_NATIVE_PORT = 9000;
@@ -58,22 +112,16 @@ export const CLICKHOUSE_PROMETHEUS_PORT = 9363;
  *  See aiDocs/patterns/clickhouse-tls-pattern.md § "The contract". */
 export const CLICKHOUSE_HTTPS_PORT = 8443;
 export 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 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 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 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 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 const CLICKHOUSE_EBS_DEVICE_NAME = "/dev/xvdf";
 /** EBS mount path on the EC2 host. */
@@ -129,6 +177,22 @@ export const CLICKHOUSE_SERVER_ROLE_TAG = {
     key: "ClickHouseRole",
     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 const CLICKHOUSE_HOST_METRICS = {
+    namespace: "CWAgent",
+    memoryMetric: "mem_used_percent",
+    diskMetric: "disk_used_percent",
+    asgDimension: "AutoScalingGroupName"
+};
 /** Shared secret generation options (all ClickHouse users share the same policy). */
 export const CLICKHOUSE_SECRET_OPTIONS = {
     excludePunctuation: true,

package/dist/lib/resources/aws/database/clickhouseUserData.js

@@ -1,4 +1,4 @@
-import { CLICKHOUSE_DATA_MOUNT_PATH, CLICKHOUSE_EBS_DEVICE_NAME, CLICKHOUSE_CONFIG_SUBDIR, CLICKHOUSE_USERS_SUBDIR, CLICKHOUSE_HTTP_PORT, CLICKHOUSE_HTTPS_PORT, CLICKHOUSE_TCP_SECURE_PORT, CLICKHOUSE_TLS_CERT_MOUNT_PATH, CLICKHOUSE_PROMETHEUS_PORT, clickHousePasswordSha256Snippet } from "./clickhouseConstants.js";
+import { CLICKHOUSE_DATA_MOUNT_PATH, CLICKHOUSE_EBS_DEVICE_NAME, CLICKHOUSE_CONFIG_SUBDIR, CLICKHOUSE_USERS_SUBDIR, CLICKHOUSE_ECS_RESERVED_MEMORY_MIB, CLICKHOUSE_HOST_METRICS, CLICKHOUSE_HTTP_PORT, CLICKHOUSE_HTTPS_PORT, CLICKHOUSE_TCP_SECURE_PORT, CLICKHOUSE_TLS_CERT_MOUNT_PATH, CLICKHOUSE_PROMETHEUS_PORT, CLICKHOUSE_UID, clickHousePasswordSha256Snippet } from "./clickhouseConstants.js";
 import { renderUsersXml } from "./clickhouseXmlRenderer.js";
 export function generateServerConfigXml(options) {
     const { backupBucketName, backupBucketRegion, coldTier } = options;
@@ -320,11 +320,76 @@ cat > "$MOUNT_POINT/server-certs/client.xml" <<'CLIENTXML'
 </config>
 CLIENTXML
 
-chown -R 101:101 "$MOUNT_POINT/server-certs"
+chown -R ${CLICKHOUSE_UID}:${CLICKHOUSE_UID} "$MOUNT_POINT/server-certs"
 chmod 600 "$MOUNT_POINT/server-certs/server.key"
 chmod 644 "$MOUNT_POINT/server-certs/client.xml"
 `
         : "";
+    // The CWAgent-namespace alarms (mem_used_percent / disk_used_percent) have
+    // no producer without this — no CloudWatch Agent is installed. The ASG name
+    // (the alarms' dimension) is unknowable at synth (LaunchTemplate → ASG is a
+    // CFN cycle), so it resolves at run time: IMDS instance tags first, with a
+    // describe-auto-scaling-instances fallback. AL2023 ECS AMIs ship no cron;
+    // systemd timer is the only scheduler present. The trailing `|| echo` keeps
+    // a publisher failure from aborting the whole database bootstrap.
+    //
+    // Hang-proofing: `Type=oneshot` defaults TimeoutStartSec to infinity and a
+    // timer never re-triggers a still-activating unit, so ONE wedged run (hung
+    // IMDS or AWS call) would silence the publisher forever — every curl carries
+    // --max-time and the unit a TimeoutStartSec under the 60s cadence. The disk
+    // metric publishes only when the data volume is actually mounted: `df` on
+    // an unmounted path reports the ROOT filesystem, a false-healthy number
+    // that would defeat the disk-critical alarm's missing-data=BREACHING flip.
+    const { namespace, memoryMetric, diskMetric, asgDimension } = CLICKHOUSE_HOST_METRICS;
+    const metricsPublisher = `
+cat > /usr/local/bin/fjall-ch-metrics.sh << 'METRICSEOF'
+#!/bin/bash
+set -euo pipefail
+IMDS_BASE="http://169.254.169.254/latest"
+TOKEN=$(curl -sf --max-time 5 -X PUT "$IMDS_BASE/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 300")
+imds() { curl -sf --max-time 5 -H "X-aws-ec2-metadata-token: $TOKEN" "$IMDS_BASE/meta-data/$1"; }
+REGION=$(imds placement/region)
+ASG=$(imds tags/instance/aws:autoscaling:groupName || true)
+if [ -z "$ASG" ]; then
+  INSTANCE_ID=$(imds instance-id)
+  ASG=$(aws autoscaling describe-auto-scaling-instances --instance-ids "$INSTANCE_ID" --region "$REGION" --query "AutoScalingInstances[0].AutoScalingGroupName" --output text)
+fi
+if [ -z "$ASG" ] || [ "$ASG" = "None" ]; then
+  echo "fjall-ch-metrics: could not resolve ASG name" >&2
+  exit 1
+fi
+MEM=$(awk '/MemTotal/{t=$2} /MemAvailable/{a=$2} END{printf "%.1f", (t-a)*100/t}' /proc/meminfo)
+METRICS=("MetricName=${memoryMetric},Dimensions=[{Name=${asgDimension},Value=$ASG}],Value=$MEM,Unit=Percent")
+if mountpoint -q ${CLICKHOUSE_DATA_MOUNT_PATH}; then
+  DISK=$(df --output=pcent ${CLICKHOUSE_DATA_MOUNT_PATH} | tail -n 1 | tr -dc '0-9')
+  METRICS+=("MetricName=${diskMetric},Dimensions=[{Name=${asgDimension},Value=$ASG}],Value=$DISK,Unit=Percent")
+else
+  echo "fjall-ch-metrics: ${CLICKHOUSE_DATA_MOUNT_PATH} not mounted, skipping disk metric" >&2
+fi
+aws cloudwatch put-metric-data --region "$REGION" --namespace ${namespace} --metric-data "\${METRICS[@]}"
+METRICSEOF
+chmod 755 /usr/local/bin/fjall-ch-metrics.sh
+cat > /etc/systemd/system/fjall-ch-metrics.service << 'SVCEOF'
+[Unit]
+Description=Publish ClickHouse host metrics to CloudWatch
+[Service]
+Type=oneshot
+TimeoutStartSec=50
+ExecStart=/usr/local/bin/fjall-ch-metrics.sh
+SVCEOF
+cat > /etc/systemd/system/fjall-ch-metrics.timer << 'TIMEREOF'
+[Unit]
+Description=Run fjall-ch-metrics every minute
+[Timer]
+OnBootSec=60s
+OnUnitActiveSec=60s
+RandomizedDelaySec=5s
+[Install]
+WantedBy=timers.target
+TIMEREOF
+systemctl daemon-reload
+systemctl enable --now fjall-ch-metrics.timer || echo "WARN: fjall-ch-metrics timer enable failed" >&2
+`;
     const script = `#!/bin/bash
 set -euo pipefail
 
@@ -357,6 +422,14 @@ DOCKEROVERRIDE
 systemctl daemon-reload
 systemctl restart docker || true
 
+# 3. Tell the ECS agent to withhold 256 MiB from advertised capacity so the
+#    scheduler accounts for kernel + agent + metrics-timer overhead instead of
+#    offering the container the host's full nominal memory. CDK appends its own
+#    'echo ECS_CLUSTER=... >> /etc/ecs/ecs.config' after this script, so >> is
+#    required here (a > would be clobber-safe only by ordering luck).
+mkdir -p /etc/ecs
+echo "ECS_RESERVED_MEMORY=${CLICKHOUSE_ECS_RESERVED_MEMORY_MIB}" >> /etc/ecs/ecs.config
+
 # Wait for the EBS volume to be attached (up to 60 seconds)
 for i in $(seq 1 60); do
   if [ -b "$DEVICE" ]; then
@@ -410,8 +483,8 @@ if [ "$USERS_CONFIG_RETRIEVED" != "1" ]; then
   exit 1
 fi
 
-chown -R 101:101 "$MOUNT_POINT"
-${tlsBootstrap}`;
+chown -R ${CLICKHOUSE_UID}:${CLICKHOUSE_UID} "$MOUNT_POINT"
+${metricsPublisher}${tlsBootstrap}`;
     return compactUserDataScript(script);
 }
 /**

package/dist/lib/resources/aws/database/rdsAurora.js

@@ -152,7 +152,7 @@ export class RdsAurora extends Construct {
         const readers = this.buildReaders(props, piEnabled, performanceInsightsKey, performanceInsightsRetention);
         const engine = props.engine ||
             DatabaseClusterEngine.auroraPostgres({
-                version: AuroraPostgresEngineVersion.of("16.10", "16")
+                version: AuroraPostgresEngineVersion.of("18.4", "18")
             });
         const parameterGroup = new ParameterGroup(this, `${this.databaseNameValue}ParameterGroup`, {
             engine,

package/dist/lib/resources/aws/database/rdsInstance.js

@@ -110,7 +110,7 @@ export class RdsInstance extends Construct {
             : undefined;
         const engine = props.engine ||
             DatabaseInstanceEngine.postgres({
-                version: PostgresEngineVersion.VER_17_5
+                version: PostgresEngineVersion.VER_17_9
             });
         const parameterGroup = new ParameterGroup(this, `${this.databaseNameValue}ParameterGroup`, {
             engine,

package/dist/lib/resources/aws/monitoring/clickhouseAlarms.d.ts

@@ -6,11 +6,11 @@ import type { Construct } from "constructs";
 export interface ClickHouseAlarmThresholds {
     /** EC2 host CPU % over 5 min. Default 90. */
     cpuThreshold?: number;
-    /** EC2 host memory % over 5 min (requires CWAgent). Default 80. */
+    /** EC2 host memory % over 5 min (CWAgent namespace). Default 80. */
     memoryThreshold?: number;
-    /** EBS root-volume disk % used. Default 70 (warn) — paired with critical at 85. */
+    /** ClickHouse data volume disk % used. Default 70 (warn) — paired with critical at 85. */
     diskWarnThreshold?: number;
-    /** EBS root-volume disk % used. Default 85. */
+    /** ClickHouse data volume disk % used. Default 85. */
     diskCriticalThreshold?: number;
 }
 export interface ClickHouseAlarmsProps {
@@ -39,8 +39,12 @@ export interface ClickHouseAlarmsProps {
     config?: ClickHouseAlarmThresholds;
 }
 /**
- * Single-node ClickHouse host-posture alarms. Covers host-level CPU + (optional)
- * memory and disk via the CloudWatch Agent metric namespace `CWAgent`, plus the
+ * Single-node ClickHouse host-posture alarms. Covers host-level CPU (AWS/EC2)
+ * plus memory and disk in the `CWAgent` namespace — fed NOT by the CloudWatch
+ * Agent (never installed on these hosts) but by the lightweight put-metric-data
+ * timer the user-data installs (see `buildClickHouseUserData`), which publishes
+ * `mem_used_percent` / `disk_used_percent` under the same names and
+ * `AutoScalingGroupName` dimension the agent would use — plus the
  * backup-failure log alarm when a backup-task log group is supplied:
  *
  * - **Backup failures** — `AccessDenied` or `S3Exception` from the backup

package/dist/lib/resources/aws/monitoring/clickhouseAlarms.js

@@ -5,9 +5,14 @@ import { Metric } from "aws-cdk-lib/aws-cloudwatch";
 import { FilterPattern, MetricFilter } from "aws-cdk-lib/aws-logs";
 import { ALARM_DEFAULTS, registerAlarm, buildAlarmDescription } from "./alarmDefaults.js";
 import { METRIC_NAMESPACE } from "./metricNamespaces.js";
+import { CLICKHOUSE_HOST_METRICS } from "../database/clickhouseConstants.js";
 /**
- * Single-node ClickHouse host-posture alarms. Covers host-level CPU + (optional)
- * memory and disk via the CloudWatch Agent metric namespace `CWAgent`, plus the
+ * Single-node ClickHouse host-posture alarms. Covers host-level CPU (AWS/EC2)
+ * plus memory and disk in the `CWAgent` namespace — fed NOT by the CloudWatch
+ * Agent (never installed on these hosts) but by the lightweight put-metric-data
+ * timer the user-data installs (see `buildClickHouseUserData`), which publishes
+ * `mem_used_percent` / `disk_used_percent` under the same names and
+ * `AutoScalingGroupName` dimension the agent would use — plus the
  * backup-failure log alarm when a backup-task log group is supplied:
  *
  * - **Backup failures** — `AccessDenied` or `S3Exception` from the backup
@@ -42,9 +47,9 @@ export function createClickHouseAlarms(props) {
     const memoryAlarm = new Alarm(scope, "ClickHouseMemoryAlarm", {
         alarmDescription: buildAlarmDescription("ClickHouse host memory utilisation exceeds threshold (CWAgent)", undefined),
         metric: new Metric({
-            namespace: "CWAgent",
-            metricName: "mem_used_percent",
-            dimensionsMap: { AutoScalingGroupName: asgName },
+            namespace: CLICKHOUSE_HOST_METRICS.namespace,
+            metricName: CLICKHOUSE_HOST_METRICS.memoryMetric,
+            dimensionsMap: { [CLICKHOUSE_HOST_METRICS.asgDimension]: asgName },
             period: ALARM_DEFAULTS.EVALUATION_PERIOD,
             statistic: "Average"
         }),
@@ -58,9 +63,9 @@ export function createClickHouseAlarms(props) {
     const diskWarnAlarm = new Alarm(scope, "ClickHouseDiskWarnAlarm", {
         alarmDescription: buildAlarmDescription("ClickHouse data volume above 70% used — plan growth response", undefined),
         metric: new Metric({
-            namespace: "CWAgent",
-            metricName: "disk_used_percent",
-            dimensionsMap: { AutoScalingGroupName: asgName },
+            namespace: CLICKHOUSE_HOST_METRICS.namespace,
+            metricName: CLICKHOUSE_HOST_METRICS.diskMetric,
+            dimensionsMap: { [CLICKHOUSE_HOST_METRICS.asgDimension]: asgName },
             period: Duration.minutes(15),
             statistic: "Average"
         }),
@@ -74,9 +79,9 @@ export function createClickHouseAlarms(props) {
     const diskCriticalAlarm = new Alarm(scope, "ClickHouseDiskCriticalAlarm", {
         alarmDescription: buildAlarmDescription("ClickHouse data volume above 85% used — imminent insert failures", undefined),
         metric: new Metric({
-            namespace: "CWAgent",
-            metricName: "disk_used_percent",
-            dimensionsMap: { AutoScalingGroupName: asgName },
+            namespace: CLICKHOUSE_HOST_METRICS.namespace,
+            metricName: CLICKHOUSE_HOST_METRICS.diskMetric,
+            dimensionsMap: { [CLICKHOUSE_HOST_METRICS.asgDimension]: asgName },
             period: Duration.minutes(5),
             statistic: "Average"
         }),
@@ -84,7 +89,11 @@ export function createClickHouseAlarms(props) {
         evaluationPeriods: 2,
         datapointsToAlarm: 2,
         comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
-        treatMissingData: TreatMissingData.NOT_BREACHING
+        // BREACHING, unlike the other host alarms: a dead metrics publisher looks
+        // identical to a full disk (no datapoints either way), and this alarm's
+        // whole job is to fire before inserts start failing. The 2×5min window
+        // absorbs the boot gap on instance replacement.
+        treatMissingData: TreatMissingData.BREACHING
     });
     registerAlarm(diskCriticalAlarm, snsAction, alarms);
     if (backupTaskLogGroup !== undefined) {

package/dist/lib/utils/engineCompat.d.ts

@@ -1,21 +1,41 @@
 import { type EngineCompat } from "@fjall/util/manifest/schemas";
+/**
+ * Normalise an npm dependency RANGE to its minimum X.Y.Z floor: strip a leading
+ * range operator (`^`, `~`, `>=`, `>`, `=`, `v`) and any prerelease/build
+ * metadata, then reconstruct `${major}.${minor}.${patch}` (missing minor/patch
+ * default to 0). Returns undefined for anything without a valid integer major —
+ * so a non-semver range (a git URL, `*`) yields no floor and the caller omits
+ * the field rather than emitting garbage.
+ */
+export declare function rangeFloor(range: string | undefined): string | undefined;
 /**
  * The constructs' own package version — the assembly's `synthesisedBy`.
  * `undefined` only when the package layout is broken enough that the upward
  * walk finds no matching `package.json`.
  */
 export declare const CONSTRUCTS_VERSION: string | undefined;
+/**
+ * The minimum `aws-cdk` CLI floor these constructs were blessed against, derived
+ * from their own `peerDependencies["aws-cdk"]` — the FM1 `minimumAwsCdkCli` emit
+ * value. `undefined` when the peer is absent or non-semver (the field is then
+ * omitted from the stamped block).
+ */
+export declare const AWS_CDK_CLI_FLOOR: string | undefined;
 /**
  * Pure core of the emitter: derive the `engineCompat` block from a given
- * version string (or undefined). Both the absent/empty guard and the
- * `${major}.0.0` non-integer-major derivation live here — the single source of
- * the derivation, delegated to by both `MINIMUM_ENGINE_VERSION` and
- * `buildEngineCompat` — so the fail-safe and malformed-version paths are
- * unit-testable directly, without mocking module-load state. Returns undefined
- * when the version is absent, empty, or has no valid integer major (fail-safe:
- * the caller stamps no block).
+ * version string (or undefined) and an optional aws-cdk CLI floor. Both the
+ * absent/empty guard and the `${major}.0.0` non-integer-major derivation live
+ * here — the single source of the derivation, delegated to by both
+ * `MINIMUM_ENGINE_VERSION` and `buildEngineCompat` — so the fail-safe and
+ * malformed-version paths are unit-testable directly, without mocking
+ * module-load state. Returns undefined when the version is absent, empty, or has
+ * no valid integer major (fail-safe: the caller stamps no block).
+ *
+ * `awsCdkCliFloor` is conditional-spread: an absent/empty floor omits
+ * `minimumAwsCdkCli` entirely (Zod-pitfall-2 safe — never `undefined`), so the
+ * FM1 check degrades to no-op rather than shipping a malformed constraint.
  */
-export declare function buildEngineCompatFrom(version: string | undefined): EngineCompat | undefined;
+export declare function buildEngineCompatFrom(version: string | undefined, awsCdkCliFloor?: string | undefined): EngineCompat | undefined;
 /**
  * The compatible deploy-engine floor for assemblies this constructs version
  * synthesises: `${major}.0.0`, derived from `CONSTRUCTS_VERSION`. `undefined`
@@ -28,10 +48,12 @@ export declare const MINIMUM_ENGINE_VERSION: string | undefined;
  * when the constructs' own version cannot be resolved (fail-safe: the caller
  * stamps no block and the deploy degrades to a constraint-free proceed).
  *
- * Phase 1 emits only the two required fields. The verdict classification of the
- * emitted floor is proven in `@fjall/deploy-core`'s
- * `orchestration/application/__tests__/engineCompat.test.ts` (a `4.0.0` floor
- * refuses a 3.x engine, proceeds for 4.x/5.x); this module's tests prove the
- * emitted shape matches that floor and reads back through the gate's reader.
+ * Emits the two required fields plus `minimumAwsCdkCli` (Phase 2 FM1) whenever the
+ * aws-cdk peer floor resolves. The verdict classification of the emitted floors is
+ * proven in `@fjall/deploy-core`'s
+ * `orchestration/application/__tests__/engineCompat.test.ts` (a `4.0.0` engine
+ * floor refuses a 3.x engine; a `minimumAwsCdkCli` floor refuses an older bundled
+ * CLI); this module's tests prove the emitted shape matches those floors and reads
+ * back through the gate's reader.
  */
 export declare function buildEngineCompat(): EngineCompat | undefined;

package/dist/lib/utils/engineCompat.js

@@ -26,10 +26,21 @@
  * hand-edit. A same-major-or-newer engine proceeds; an older-major engine
  * hard-refuses.
  *
- * The optional `maximumEngineMajor` / `minimumAwsCdkCli` bounds are deliberately
- * NOT emitted in Phase 1 — they are ADR open question Q5 (engine-ahead cap) and
- * the Phase-2 FM1 aws-cdk floor graft respectively, both unresolved and
- * deferred. This emitter stamps only the two required fields.
+ * `minimumAwsCdkCli` (Phase 2, FM1) is the floor for the deploy engine's bundled
+ * `aws-cdk` CLI: an engine whose CLI is older than the version these constructs
+ * were blessed against cannot reliably read the cloud assembly they synthesised.
+ * The aws-cdk CLI and aws-cdk-lib version axes DIVERGED in CDK v2 (CLI ~2.1134.x
+ * vs lib ~2.262.x), so this is a distinct check from `minimumEngineVersion`, on a
+ * different axis. It is derived from the constructs' OWN
+ * `peerDependencies["aws-cdk"]` floor — self-honest, and shipped with the package
+ * (unlike the blessed-pin JSON, which is not in `files`) — and conditional-spread
+ * so a package whose peer floor cannot be resolved simply omits it (fail-safe: the
+ * FM1 check degrades to no-op rather than emitting a garbage floor).
+ *
+ * The optional `maximumEngineMajor` bound is deliberately NOT emitted — it is ADR
+ * open question Q5 (engine-ahead cap), and capping a newer engine would break the
+ * normal fjall-upgrade-then-redeploy path. The classifier still honours one if a
+ * future assembly stamps it by hand; this emitter never does.
  *
  * Fail-safe: if the constructs' own version cannot be resolved (a broken
  * package layout), `buildEngineCompat` returns undefined and the caller stamps
@@ -43,7 +54,41 @@ import { existsSync, readFileSync } from "fs";
 import { getErrorMessage, maskSensitiveOutput } from "@fjall/util";
 import { FjallLogger } from "./validationLogger.js";
 const PACKAGE_NAME = "@fjall/components-infrastructure";
-function resolveConstructsVersion() {
+/**
+ * Normalise an npm dependency RANGE to its minimum X.Y.Z floor: strip a leading
+ * range operator (`^`, `~`, `>=`, `>`, `=`, `v`) and any prerelease/build
+ * metadata, then reconstruct `${major}.${minor}.${patch}` (missing minor/patch
+ * default to 0). Returns undefined for anything without a valid integer major —
+ * so a non-semver range (a git URL, `*`) yields no floor and the caller omits
+ * the field rather than emitting garbage.
+ */
+export function rangeFloor(range) {
+    if (range === undefined || range.length === 0)
+        return undefined;
+    const firstToken = range.trim().split(/\s+/)[0] ?? "";
+    const core = firstToken.replace(/^[\^~>=v ]+/i, "").split(/[-+]/)[0] ?? "";
+    if (core.length === 0)
+        return undefined;
+    const parts = core.split(".");
+    const major = Number(parts[0]);
+    const minor = parts.length > 1 ? Number(parts[1]) : 0;
+    const patch = parts.length > 2 ? Number(parts[2]) : 0;
+    if (!Number.isInteger(major) || major < 0)
+        return undefined;
+    if (!Number.isInteger(minor) || minor < 0)
+        return undefined;
+    if (!Number.isInteger(patch) || patch < 0)
+        return undefined;
+    return `${major}.${minor}.${patch}`;
+}
+/**
+ * Resolve the constructs' own package.json (version + aws-cdk peer floor) by the
+ * same upward `name`-matching walk `DEPLOY_CORE_VERSION` uses — robust across the
+ * source (`lib/utils/`) and compiled (`dist/lib/utils/`) layouts, and skipping any
+ * unrelated `package.json` higher up (a consuming app's). Returns undefined only
+ * when the walk finds no matching `package.json` (broken layout).
+ */
+function resolveConstructsPackageMeta() {
     try {
         let dir = dirname(fileURLToPath(import.meta.url));
         const { root } = parse(dir);
@@ -54,7 +99,13 @@ function resolveConstructsVersion() {
                 if (pkg.name === PACKAGE_NAME &&
                     typeof pkg.version === "string" &&
                     pkg.version.length > 0) {
-                    return pkg.version;
+                    const awsCdkPeer = pkg.peerDependencies?.["aws-cdk"];
+                    return {
+                        version: pkg.version,
+                        awsCdkCliFloor: typeof awsCdkPeer === "string"
+                            ? rangeFloor(awsCdkPeer)
+                            : undefined
+                    };
                 }
             }
             if (dir === root)
@@ -63,28 +114,40 @@ function resolveConstructsVersion() {
         }
     }
     catch (error) {
-        FjallLogger.warn(`Could not resolve ${PACKAGE_NAME} version for engineCompat: ` +
+        FjallLogger.warn(`Could not resolve ${PACKAGE_NAME} metadata for engineCompat: ` +
             maskSensitiveOutput(getErrorMessage(error)));
         return undefined;
     }
 }
+const CONSTRUCTS_PACKAGE_META = resolveConstructsPackageMeta();
 /**
  * The constructs' own package version — the assembly's `synthesisedBy`.
  * `undefined` only when the package layout is broken enough that the upward
  * walk finds no matching `package.json`.
  */
-export const CONSTRUCTS_VERSION = resolveConstructsVersion();
+export const CONSTRUCTS_VERSION = CONSTRUCTS_PACKAGE_META?.version;
+/**
+ * The minimum `aws-cdk` CLI floor these constructs were blessed against, derived
+ * from their own `peerDependencies["aws-cdk"]` — the FM1 `minimumAwsCdkCli` emit
+ * value. `undefined` when the peer is absent or non-semver (the field is then
+ * omitted from the stamped block).
+ */
+export const AWS_CDK_CLI_FLOOR = CONSTRUCTS_PACKAGE_META?.awsCdkCliFloor;
 /**
  * Pure core of the emitter: derive the `engineCompat` block from a given
- * version string (or undefined). Both the absent/empty guard and the
- * `${major}.0.0` non-integer-major derivation live here — the single source of
- * the derivation, delegated to by both `MINIMUM_ENGINE_VERSION` and
- * `buildEngineCompat` — so the fail-safe and malformed-version paths are
- * unit-testable directly, without mocking module-load state. Returns undefined
- * when the version is absent, empty, or has no valid integer major (fail-safe:
- * the caller stamps no block).
+ * version string (or undefined) and an optional aws-cdk CLI floor. Both the
+ * absent/empty guard and the `${major}.0.0` non-integer-major derivation live
+ * here — the single source of the derivation, delegated to by both
+ * `MINIMUM_ENGINE_VERSION` and `buildEngineCompat` — so the fail-safe and
+ * malformed-version paths are unit-testable directly, without mocking
+ * module-load state. Returns undefined when the version is absent, empty, or has
+ * no valid integer major (fail-safe: the caller stamps no block).
+ *
+ * `awsCdkCliFloor` is conditional-spread: an absent/empty floor omits
+ * `minimumAwsCdkCli` entirely (Zod-pitfall-2 safe — never `undefined`), so the
+ * FM1 check degrades to no-op rather than shipping a malformed constraint.
  */
-export function buildEngineCompatFrom(version) {
+export function buildEngineCompatFrom(version, awsCdkCliFloor) {
     if (version === undefined || version.length === 0)
         return undefined;
     const major = Number(version.split(".")[0]);
@@ -92,7 +155,9 @@ export function buildEngineCompatFrom(version) {
         return undefined;
     return {
         synthesisedBy: version,
-        minimumEngineVersion: `${major}.0.0`
+        minimumEngineVersion: `${major}.0.0`,
+        ...(awsCdkCliFloor !== undefined &&
+            awsCdkCliFloor.length > 0 && { minimumAwsCdkCli: awsCdkCliFloor })
     };
 }
 /**
@@ -107,12 +172,14 @@ export const MINIMUM_ENGINE_VERSION = buildEngineCompatFrom(CONSTRUCTS_VERSION)?
  * when the constructs' own version cannot be resolved (fail-safe: the caller
  * stamps no block and the deploy degrades to a constraint-free proceed).
  *
- * Phase 1 emits only the two required fields. The verdict classification of the
- * emitted floor is proven in `@fjall/deploy-core`'s
- * `orchestration/application/__tests__/engineCompat.test.ts` (a `4.0.0` floor
- * refuses a 3.x engine, proceeds for 4.x/5.x); this module's tests prove the
- * emitted shape matches that floor and reads back through the gate's reader.
+ * Emits the two required fields plus `minimumAwsCdkCli` (Phase 2 FM1) whenever the
+ * aws-cdk peer floor resolves. The verdict classification of the emitted floors is
+ * proven in `@fjall/deploy-core`'s
+ * `orchestration/application/__tests__/engineCompat.test.ts` (a `4.0.0` engine
+ * floor refuses a 3.x engine; a `minimumAwsCdkCli` floor refuses an older bundled
+ * CLI); this module's tests prove the emitted shape matches those floors and reads
+ * back through the gate's reader.
  */
 export function buildEngineCompat() {
-    return buildEngineCompatFrom(CONSTRUCTS_VERSION);
+    return buildEngineCompatFrom(CONSTRUCTS_VERSION, AWS_CDK_CLI_FLOOR);
 }