@fjall/components-infrastructure 2.17.0 → 2.18.0

package/dist/lib/lambda-assets/cert-generator/asset/index.js

@@ -17897,6 +17897,15 @@ ${body}
 -----END PRIVATE KEY-----
 `;
 }
+function certPhysicalResourceId(event, caSecretArn, serverSecretArn) {
+  if (event.RequestType === "Update" && event.PhysicalResourceId) {
+    return event.PhysicalResourceId;
+  }
+  const digest = createHash("sha256").update(`${caSecretArn}
+${serverSecretArn}`).digest("hex").slice(0, 16);
+  return `tls-cert-${digest}`;
+}
+exports.certPhysicalResourceId = certPhysicalResourceId;
 exports.handler = async (event) => {
   if (event.RequestType === "Delete") {
     const props2 = event.ResourceProperties || {};
@@ -17964,7 +17973,11 @@ exports.handler = async (event) => {
     throw err;
   }
   return {
-    PhysicalResourceId: `tls-cert-${caCertSha256.slice(0, 16)}`,
+    PhysicalResourceId: certPhysicalResourceId(
+      event,
+      caSecretArn,
+      serverSecretArn
+    ),
     Data: { CaCertSha256: caCertSha256 }
   };
 };

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

@@ -5,6 +5,7 @@ import { Construct } from "constructs";
 import { Secret, type SecretImport } from "../../resources/aws/secrets/secret.js";
 import { type ClickHouseSchemaAdmin, type ProfileSpec } from "../../resources/aws/database/clickhouseSchemas.js";
 import { type ISecret } from "aws-cdk-lib/aws-secretsmanager";
+import { type ITopic } from "aws-cdk-lib/aws-sns";
 import type { ClickHouseTlsOptions } from "./clickhouseTls/index.js";
 import { type ClickHouseMigrationsConfig, type IClickHouseDatabase } from "./interfaces/database.js";
 import { type ISecurityGroupConnector } from "./interfaces/connector.js";
@@ -115,6 +116,22 @@ export interface ClickHouseDatabaseProps {
      * See ./clickhouseTls/types.ts.
      */
     tls?: ClickHouseTlsOptions;
+    /**
+     * Ops alarm SNS topic for the ClickHouse host-posture alarms (CPU / memory /
+     * disk warn+critical) and — when `backupSchedule` is enabled — the
+     * backup-failure alarm. Accepts an `ITopic`, an `arn:` string, or the
+     * `"import:<ExportName>"` form the generator scaffolds onto production apps
+     * (`"import:SharedAlarmTopicArn"`). Forwarded automatically by
+     * `DatabaseFactory.build` from `BaseDatabaseProps.alertsTopic`. Omitted (the
+     * default) → no host alarms, matching the dormant pre-dogfood behaviour.
+     *
+     * Resolved internally via `resolveAlertsTopic`; the construct owns the
+     * `instanceRole` / `asgName` / `backupTaskLogGroup` the alarms need, so no
+     * caller wiring is required. The stuck-merge alarm is NOT declared here —
+     * `"Stuck merge detected"` is emitted by the webapp app process, so it lives
+     * on the app service's declarative `logAlarms` instead.
+     */
+    alertsTopic?: ITopic | string;
 }
 /**
  * ClickHouse analytics database wrapper implementing IClickHouseDatabase.

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

@@ -18,6 +18,8 @@ import { LogGroup } from "../../resources/aws/logging/logGroup.js";
 import { createClickHouseSecurityGroup } from "../../resources/aws/database/clickhouseSecurityGroup.js";
 import { buildClickHouseEntrypointWrapper, buildClickHouseUserData, generateUsersConfigXml } from "../../resources/aws/database/clickhouseUserData.js";
 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 { 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";
@@ -480,6 +482,20 @@ export class ClickHouseDatabase extends Construct {
             tlsCaSecret.grantRead(instanceRole);
         if (tlsServerSecret !== undefined)
             tlsServerSecret.grantRead(instanceRole);
+        // 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.
+        const resolvedAlertsTopic = resolveAlertsTopic(this, "AlertsTopic", props.alertsTopic);
+        const asgName = ecsCompute.getAutoScalingGroupName();
+        if (resolvedAlertsTopic !== undefined && asgName !== undefined) {
+            createClickHouseAlarms({
+                scope: this,
+                instanceRole,
+                asgName,
+                alarmTopic: resolvedAlertsTopic,
+                ...(backupTaskLogGroup !== undefined && { backupTaskLogGroup })
+            });
+        }
         const adminSecretName = clickHouseUserSecretName(schemaAdmin.name);
         // Password via CLICKHOUSE_CLIENT_PASSWORD env, not --password on argv
         // (argv → /proc/<pid>/cmdline). `jq -r .password` on an empty pipeline

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

@@ -3,10 +3,10 @@ import { type Construct } from "constructs";
 import { type SecretImport } from "../../resources/aws/secrets/index.js";
 import { type ComputeType, type IEcsCompute, type ILambdaCompute, type IEc2Compute, type AnyCompute, isCompute, isEcsCompute, isLambdaCompute, isEc2Compute } from "./interfaces/compute.js";
 import type App from "../../app.js";
-import { EcsCompute, type EcsComputeProps, type EcsServiceConfig, type EcsContainerConfig, type EcsScalingConfig, type EcsClusterConfig, type EcsRoutingConfig, type EcsCapacityProviderConfig, type ContainerDependency, type EcsMigrationsConfig, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, type EcsCapacityProvider, type Ec2CapacityConfig, validateEcsProps, buildContainerConfigs, expandMigrationsSugar, type ResolvedScalingConfig, resolveScalingConfig } from "./computeEcs.js";
+import { EcsCompute, type EcsComputeProps, type EcsServiceConfig, type ServiceLogAlarm, type EcsContainerConfig, type EcsScalingConfig, type EcsClusterConfig, type EcsRoutingConfig, type EcsCapacityProviderConfig, type ContainerDependency, type EcsMigrationsConfig, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, type EcsCapacityProvider, type Ec2CapacityConfig, validateEcsProps, buildContainerConfigs, expandMigrationsSugar, type ResolvedScalingConfig, resolveScalingConfig } from "./computeEcs.js";
 import { LambdaCompute, type LambdaComputeProps, type ContainerLambdaProps, type CodeLambdaProps, type FunctionUrlConfig, type ResolvedLambdaDeployment, resolveLambdaDeployment, Architecture, HttpMethod, InvokeMode, type FunctionUrlCorsOptions } from "./computeLambda.js";
 import { Ec2Compute, type Ec2ComputeProps, type SshConfig } from "./computeEc2.js";
-export { EcsCompute, type EcsComputeProps, type EcsServiceConfig, type EcsContainerConfig, type EcsScalingConfig, type EcsClusterConfig, type EcsRoutingConfig, type EcsCapacityProviderConfig, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, type EcsCapacityProvider, type Ec2CapacityConfig, type ContainerDependency, type EcsMigrationsConfig, validateEcsProps, buildContainerConfigs, expandMigrationsSugar, type ResolvedScalingConfig, resolveScalingConfig, LambdaCompute, type LambdaComputeProps, type ContainerLambdaProps, type CodeLambdaProps, type FunctionUrlConfig, type ResolvedLambdaDeployment, resolveLambdaDeployment, Architecture, HttpMethod, InvokeMode, type FunctionUrlCorsOptions, Ec2Compute, type Ec2ComputeProps, type SshConfig };
+export { EcsCompute, type EcsComputeProps, type EcsServiceConfig, type ServiceLogAlarm, type EcsContainerConfig, type EcsScalingConfig, type EcsClusterConfig, type EcsRoutingConfig, type EcsCapacityProviderConfig, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, type EcsCapacityProvider, type Ec2CapacityConfig, type ContainerDependency, type EcsMigrationsConfig, validateEcsProps, buildContainerConfigs, expandMigrationsSugar, type ResolvedScalingConfig, resolveScalingConfig, LambdaCompute, type LambdaComputeProps, type ContainerLambdaProps, type CodeLambdaProps, type FunctionUrlConfig, type ResolvedLambdaDeployment, resolveLambdaDeployment, Architecture, HttpMethod, InvokeMode, type FunctionUrlCorsOptions, Ec2Compute, type Ec2ComputeProps, type SshConfig };
 export type { ComputeType } from "./interfaces/compute.js";
 /**
  * Configuration defaults for each compute type.

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

@@ -7,7 +7,7 @@ import { type IEcsCompute } from "./interfaces/compute.js";
 import { type SecretImport } from "../../resources/aws/secrets/index.js";
 import EcsCluster, { type EcsClusterProps } from "../../resources/aws/compute/ecs.js";
 export { ScalingType } from "./computeEcsTypes.js";
-export type { EcsCapacityProvider, Ec2CapacityConfig, RemoteConnectionSpec, EcsCapacityProviderConfig, EcsContainerConfig, ContainerDependency, ContainerVolume, EcsScheduledTaskConfig, EcsLifecycleHookMigrationsConfig, EcsPostDeployMigrationsConfig, EcsHookMigrationsConfig, EcsMigrationsConfig, EcsMigrationsMode, EcsCircuitBreakerConfig, EcsScalingConfig, EcsClusterConfig, EcsRoutingConfig, EcsServiceConfig, EcsComputeProps } from "./computeEcsTypes.js";
+export type { EcsCapacityProvider, Ec2CapacityConfig, RemoteConnectionSpec, EcsCapacityProviderConfig, EcsContainerConfig, ContainerDependency, ContainerVolume, EcsScheduledTaskConfig, EcsLifecycleHookMigrationsConfig, EcsPostDeployMigrationsConfig, EcsHookMigrationsConfig, EcsMigrationsConfig, EcsMigrationsMode, EcsCircuitBreakerConfig, EcsScalingConfig, EcsClusterConfig, EcsRoutingConfig, EcsServiceConfig, ServiceLogAlarm, EcsComputeProps } from "./computeEcsTypes.js";
 import { ScalingType, type EcsCapacityProviderConfig, type EcsCapacityProvider, type EcsContainerConfig, type EcsScalingConfig, type EcsServiceConfig, type EcsComputeProps, type QueueScalingConfig } from "./computeEcsTypes.js";
 export declare const ECS_CAPACITY_PROVIDER_CONFIG: Record<EcsCapacityProvider, EcsCapacityProviderConfig>;
 export declare function getEcsCapacityProviderConfig(provider: EcsCapacityProvider): EcsCapacityProviderConfig;
@@ -124,6 +124,17 @@ export declare class EcsCompute extends Construct implements IEcsCompute {
      * migrate container injected by `expandMigrationsSugar`.
      */
     private wireLifecycleHookMigrations;
+    /**
+     * Wire a native CloudFormation `DependsOn` from each service that declares
+     * `awaitMigrationsFrom` to the named migrate-owning service, so CFN does not
+     * roll out the dependent service until the target's ECS deployment — including
+     * its PRE_SCALE_UP migrate hook — has completed. Prevents the RDS-IAM auth /
+     * schema-mismatch race when a DB-connecting worker starts before the app's
+     * migrations have applied, and enables a single-pass greenfield deploy.
+     * Shape (target exists, declares hook migrations, no self / cycle) is already
+     * guaranteed by `validateEcsProps`; the undefined guards are synth invariants.
+     */
+    private wireServiceMigrationDependencies;
     /**
      * Synthesise a dedicated migration task definition for a lifecycle-hook
      * migration when `separateTaskDef` is set. Creates the migration's own

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

@@ -154,6 +154,39 @@ export function validateEcsProps(props) {
             validateSeparateTaskDef(service.name, service.migrations.separateTaskDef);
         }
     }
+    // Validate awaitMigrationsFrom cross-service migration ordering.
+    const serviceByName = new Map(props.services.map((s) => [s.name, s]));
+    for (const service of props.services) {
+        const target = service.awaitMigrationsFrom;
+        if (target === undefined)
+            continue;
+        if (target === service.name) {
+            throw new Error(`Service '${service.name}': awaitMigrationsFrom cannot reference its own migrations.`);
+        }
+        const targetService = serviceByName.get(target);
+        if (targetService === undefined) {
+            throw new Error(`Service '${service.name}': awaitMigrationsFrom names unknown service '${target}'. ` +
+                "It must name another service in the same cluster.");
+        }
+        if (targetService.migrations === undefined ||
+            !isHookMigrations(targetService.migrations)) {
+            throw new Error(`Service '${service.name}': awaitMigrationsFrom names service '${target}', which does not ` +
+                "declare lifecycle-hook or post-deploy migrations. Only those modes have a single " +
+                "completion point to await (init-container migrations run per-replica).");
+        }
+    }
+    // Detect cycles in the awaitMigrationsFrom graph (each service awaits <=1 other).
+    for (const service of props.services) {
+        const seen = new Set();
+        let current = service.name;
+        while (current !== undefined) {
+            if (seen.has(current)) {
+                throw new Error(`Service '${service.name}': awaitMigrationsFrom forms a dependency cycle.`);
+            }
+            seen.add(current);
+            current = serviceByName.get(current)?.awaitMigrationsFrom;
+        }
+    }
     if (props.cluster?.directAccess === true) {
         const hasEc2Service = props.services.some((s) => s.capacityProvider === "EC2");
         if (!hasEc2Service) {
@@ -722,6 +755,8 @@ export class EcsCompute extends Construct {
                 ssmSecretsPath: service.ssmSecretsPath,
                 docker: service.docker,
                 alarms: service.alarms,
+                logAlarms: service.logAlarms,
+                logMetricNamespace: service.logMetricNamespace,
                 circuitBreaker: service.circuitBreaker,
                 ...(service.deployment !== undefined && {
                     deployment: service.deployment
@@ -763,6 +798,7 @@ export class EcsCompute extends Construct {
         this.ecsCluster = new EcsCluster(this, `${id}Ecs`, ecsProps);
         this.connections = this.ecsCluster.connections;
         this.wireLifecycleHookMigrations(props.services);
+        this.wireServiceMigrationDependencies(props.services);
         this.materialiseScheduledTasks(id, props);
     }
     /**
@@ -985,6 +1021,27 @@ export class EcsCompute extends Construct {
             });
         }
     }
+    /**
+     * Wire a native CloudFormation `DependsOn` from each service that declares
+     * `awaitMigrationsFrom` to the named migrate-owning service, so CFN does not
+     * roll out the dependent service until the target's ECS deployment — including
+     * its PRE_SCALE_UP migrate hook — has completed. Prevents the RDS-IAM auth /
+     * schema-mismatch race when a DB-connecting worker starts before the app's
+     * migrations have applied, and enables a single-pass greenfield deploy.
+     * Shape (target exists, declares hook migrations, no self / cycle) is already
+     * guaranteed by `validateEcsProps`; the undefined guards are synth invariants.
+     */
+    wireServiceMigrationDependencies(services) {
+        for (const svcConfig of services) {
+            if (svcConfig.awaitMigrationsFrom === undefined)
+                continue;
+            const dependent = this.ecsCluster.getService(svcConfig.name);
+            const dependency = this.ecsCluster.getService(svcConfig.awaitMigrationsFrom);
+            if (dependent !== undefined && dependency !== undefined) {
+                dependent.node.addDependency(dependency);
+            }
+        }
+    }
     /**
      * Synthesise a dedicated migration task definition for a lifecycle-hook
      * migration when `separateTaskDef` is set. Creates the migration's own

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

@@ -8,7 +8,7 @@ import { type ConnectionSpec } from "./interfaces/connector.js";
 import { type RemoteConnectionSpec } from "../../resources/aws/compute/ecsRemoteConnections.js";
 import { type EcsRoutingConfig, type EcsContainerDependency } from "../../resources/aws/compute/ecsTypes.js";
 import { ScalingType, type DomainConfig, type EcsCapacityProvider, type Ec2CapacityConfig, type QueueScalingConfig } from "../../resources/aws/compute/ecs.js";
-import type { EcsServiceAlarmThresholds } from "../../resources/aws/monitoring/index.js";
+import type { EcsServiceAlarmThresholds, LogPatternAlarmSpec } from "../../resources/aws/monitoring/index.js";
 import { type SecretImport } from "../../resources/aws/secrets/index.js";
 import type { DockerBuild } from "@fjall/util/manifest/schemas";
 export type { RemoteConnectionSpec };
@@ -39,6 +39,13 @@ export interface EcsCapacityProviderConfig {
  * @see https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDependency.html
  */
 export type ContainerDependency = EcsContainerDependency;
+/**
+ * A log-pattern alarm declared on a service: a CloudWatch metric filter over the
+ * service's log group plus the alarm that fires on a match. Public-facing alias
+ * for the canonical resource-layer `LogPatternAlarmSpec`, re-exported so factory
+ * consumers can declare `logAlarms` from the patterns barrel.
+ */
+export type ServiceLogAlarm = LogPatternAlarmSpec;
 /**
  * Configuration for a container in an ECS task.
  *
@@ -729,6 +736,20 @@ export interface EcsServiceConfig {
      * - object: override specific thresholds
      */
     alarms?: EcsServiceAlarmThresholds | false;
+    /**
+     * Log-pattern alarms for this service. Each entry creates a CloudWatch metric
+     * filter over the service's log group plus an alarm wired to the cluster's
+     * `alertsTopic` — so it materialises only when `alertsTopic` is set and
+     * `alarms !== false`. Declarative: describe the match with `literal` or
+     * `anyTerms`.
+     */
+    logAlarms?: ServiceLogAlarm[];
+    /**
+     * Default CloudWatch metric namespace for this service's `logAlarms`. Each
+     * entry may override it per-alarm (e.g. `Fjall/WebApp` for app alarms,
+     * `Fjall/ClickHouse` for a relocated stuck-merge alarm on the same service).
+     */
+    logMetricNamespace?: string;
     /**
      * Run an init container before any other container in this service starts.
      * Synthesises a non-essential container with the given migration command,
@@ -739,6 +760,35 @@ export interface EcsServiceConfig {
      * migrations: { command: ["npx", "payload", "migrate"] }
      */
     migrations?: EcsMigrationsConfig;
+    /**
+     * Names another service in the same cluster whose **lifecycle-hook** (or
+     * post-deploy) migrations must finish before this service rolls out.
+     *
+     * Implemented as a native CloudFormation `DependsOn`: CFN will not begin
+     * creating or updating this service until the named service's ECS deployment
+     * — including its PRE_SCALE_UP migrate hook — has completed. Use it for
+     * DB-connecting workers that must not start until the migrate-owning service
+     * has applied role / grant / schema migrations; without it, a worker can
+     * attempt RDS-IAM auth before the migrate task has run `GRANT rds_iam` (the
+     * race that aborts a migration-bearing deploy). Also enables a single-pass
+     * greenfield deploy (app migrates, then workers come up, in one `cdk deploy`).
+     *
+     * Works for EC2-capacity services — it is a resource-ordering edge, not a
+     * worker-side lifecycle hook, so the FARGATE-only restriction on hook
+     * migrations does not apply here.
+     *
+     * The named service MUST declare `migrations` in `lifecycle-hook` or
+     * `post-deploy` mode — init-container migrations run per-replica and have no
+     * single completion point to await. Validated at synth (target exists,
+     * declares hook migrations, no self-reference, no cycle).
+     *
+     * Escape hatch for orderings this field can't express: drop to the L2 API,
+     * `cluster.getService("x")?.node.addDependency(cluster.getService("y")!)`.
+     *
+     * @example
+     * awaitMigrationsFrom: "app"
+     */
+    awaitMigrationsFrom?: string;
     /**
      * Deployment circuit breaker policy. Omit for the safe default
      * `{ enable: true, rollback: true }` — failed deployments automatically

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

@@ -131,6 +131,14 @@ export interface InstanceDatabaseProps extends BaseDatabaseProps {
     credentials?: CredentialsConfig;
     encryption?: EncryptionConfig;
     publiclyAccessible?: boolean;
+    /**
+     * Enable RDS IAM database authentication (opt-in; default off). Instance
+     * databases only. When true, IAM principals granted via
+     * {@link RelationalDatabase.grantIamConnect} connect with short-lived
+     * `rds-db:connect` tokens instead of a stored password. See ADR
+     * decisions/2026-06-17-rls-role-auth-and-launch-gating.md.
+     */
+    iamAuthentication?: boolean;
     /** ARN or identifier of DB instance snapshot to restore from */
     snapshotIdentifier?: string;
     /** Username from the snapshot (required when restoring from snapshot to reset password) */
@@ -247,7 +255,7 @@ export declare class RelationalDatabase extends Construct implements IRelational
     private database;
     constructor(scope: Construct, id: string, props: IRelationalDatabaseProps);
     private resolveAlertsTopic;
-    addDatabase(props: IRelationalDatabaseProps): void;
+    private addDatabase;
     private addAurora;
     private addAuroraGlobal;
     private addRdsInstance;
@@ -278,6 +286,16 @@ export declare class RelationalDatabase extends Construct implements IRelational
      * @param grantee The connectable principal to grant connect permissions to
      */
     grantConnect(grantee: IConnectable): void;
+    /**
+     * Grant an IAM principal permission to connect as `dbUsername` via RDS IAM
+     * database authentication. Instance databases only — Aurora uses a different
+     * mechanism, so this throws for non-Instance databases. Requires the instance
+     * to be created with `iamAuthentication: true`. The L2 `grantConnect` scopes
+     * `rds-db:connect` to the exact `dbuser:<resourceId>/<dbUsername>` ARN — never
+     * a bare wildcard. See ADR
+     * decisions/2026-06-17-rls-role-auth-and-launch-gating.md.
+     */
+    grantIamConnect(grantee: IGrantable, dbUsername: string): Grant;
 }
 export { ClickHouseDatabase, type ClickHouseDatabaseProps };
 export { ClickHouseDefaultProfiles, ClickHouseSchemaAdminSchema, ManagedPasswordNameSchema, ProfileSpecSchema, type ClickHouseSchemaAdmin, type ManagedPasswordName, type ProfileSpec } from "../../resources/aws/database/clickhouseSchemas.js";

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

@@ -118,7 +118,7 @@ function validateRelationalDatabaseProps(props) {
             "Specify the AWS region where the primary cluster will be created.");
     }
     // Instance-only options on Aurora/GlobalAurora
-    warnIfPropertiesIgnored(props, ["readReplica", "multiAz", "allocatedStorage"], "Instance", "Instance database");
+    warnIfPropertiesIgnored(props, ["readReplica", "multiAz", "allocatedStorage", "iamAuthentication"], "Instance", "Instance database");
     // Aurora-only options on Instance
     warnIfPropertiesIgnored(props, ["readers", "writer", "backupRetention"], ["Aurora", "GlobalAurora"], "Aurora database");
     // GlobalAurora-only options on non-global databases
@@ -328,6 +328,8 @@ export class RelationalDatabase extends Construct {
         return resolveAlertsTopicShared(this, "AlertsTopic", alertsTopic);
     }
     addDatabase(props) {
+        // Re-asserted here (the constructor already validates) to narrow
+        // `props.vpc` to `IVpc` for the type-specific add* dispatch below.
         validateRelationalDatabaseProps(props);
         switch (props.type) {
             case "Aurora":
@@ -440,7 +442,8 @@ export class RelationalDatabase extends Construct {
             snapshotUsername: props.snapshotUsername,
             alertsTopic: this.resolveAlertsTopic(props.alertsTopic),
             alarms: props.alarms,
-            applicationId: props.applicationId
+            applicationId: props.applicationId,
+            iamAuthentication: props.iamAuthentication
         });
         this.connections = this.database.connections;
         this.addDatabaseOutputs(props);
@@ -595,6 +598,22 @@ export class RelationalDatabase extends Construct {
     grantConnect(grantee) {
         this.connections.allowDefaultPortFrom(grantee);
     }
+    /**
+     * Grant an IAM principal permission to connect as `dbUsername` via RDS IAM
+     * database authentication. Instance databases only — Aurora uses a different
+     * mechanism, so this throws for non-Instance databases. Requires the instance
+     * to be created with `iamAuthentication: true`. The L2 `grantConnect` scopes
+     * `rds-db:connect` to the exact `dbuser:<resourceId>/<dbUsername>` ARN — never
+     * a bare wildcard. See ADR
+     * decisions/2026-06-17-rls-role-auth-and-launch-gating.md.
+     */
+    grantIamConnect(grantee, dbUsername) {
+        if (!(this.database instanceof RdsInstance)) {
+            throw new Error(`grantIamConnect is only supported for Instance databases; ` +
+                `'${this._databaseName}' is a ${this.databaseType} database.`);
+        }
+        return this.database.grantIamConnect(grantee, dbUsername);
+    }
 }
 export { ClickHouseDatabase };
 export { ClickHouseDefaultProfiles, ClickHouseSchemaAdminSchema, ManagedPasswordNameSchema, ProfileSpecSchema } from "../../resources/aws/database/clickhouseSchemas.js";

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

@@ -4,7 +4,7 @@ import { Construct } from "constructs";
 import { CfnOutput, Aspects } from "aws-cdk-lib";
 import { processConnections } from "../../../utils/connections.js";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
-import { createEcsServiceAlarms } from "../monitoring/index.js";
+import { createEcsServiceAlarms, createLogPatternAlarms } from "../monitoring/index.js";
 // Extracted modules
 import { CapacityProviderDependencyAspect } from "./ecsCapacityProviderAspect.js";
 import { validateEcsClusterProps } from "./ecsValidation.js";
@@ -210,7 +210,7 @@ export default class EcsCluster extends Construct {
         const executionRole = createExecutionRole(this.ctx, serviceName);
         const taskRole = createTaskRole(this.ctx, serviceName, serviceProps);
         const taskDefinition = createTaskDefinition(this.ctx, serviceName, serviceProps, executionRole, taskRole);
-        const { containers, primaryContainer } = addContainersToTask(this.ctx, serviceName, serviceProps, taskDefinition);
+        const { containers, primaryContainer, logGroup } = addContainersToTask(this.ctx, serviceName, serviceProps, taskDefinition);
         const service = createService(this.ctx, serviceName, serviceProps, taskDefinition, this.asgState);
         let targetGroup;
         if (!this.loadBalancerDisabled &&
@@ -230,7 +230,8 @@ export default class EcsCluster extends Construct {
             containers,
             primaryContainer,
             targetGroup,
-            scalingPolicy
+            scalingPolicy,
+            logGroup
         });
         if (serviceProps.connections && serviceProps.connections.length > 0) {
             try {
@@ -253,6 +254,16 @@ export default class EcsCluster extends Construct {
                 alarmTopic: this.props.alertsTopic,
                 applicationId: this.props.applicationId
             });
+            if (serviceProps.logAlarms && serviceProps.logAlarms.length > 0) {
+                createLogPatternAlarms({
+                    scope: this,
+                    logGroup,
+                    alarmTopic: this.props.alertsTopic,
+                    metricNamespace: serviceProps.logMetricNamespace,
+                    specs: serviceProps.logAlarms,
+                    applicationId: this.props.applicationId
+                });
+            }
         }
     }
     setupConnections(props) {

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

@@ -1,8 +1,10 @@
 import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
+import { RetentionDays } from "aws-cdk-lib/aws-logs";
 export declare const DEFAULT_EC2_INSTANCE_TYPE = "t4g.micro";
 export declare const DEFAULT_WARM_POOL_MIN_SIZE = 1;
 export declare const DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN = false;
 export declare const DEFAULT_LOG_RETENTION_DAYS = 14;
+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;

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

@@ -1,4 +1,5 @@
 import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
+import { RetentionDays } from "aws-cdk-lib/aws-logs";
 // Canonical source: @fjall/generator schemas/constants.ts — keep in sync
 export const DEFAULT_EC2_INSTANCE_TYPE = "t4g.micro";
 export const DEFAULT_WARM_POOL_MIN_SIZE = 1;
@@ -8,6 +9,9 @@ export const DEFAULT_WARM_POOL_MIN_SIZE = 1;
 export const DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN = false;
 // 14 days balances cost against retaining enough history for post-mortem debugging
 export const DEFAULT_LOG_RETENTION_DAYS = 14;
+// The RetentionDays enum the explicit service LogGroup needs. Coupled to
+// DEFAULT_LOG_RETENTION_DAYS (TWO_WEEKS === 14) — the two must move together.
+export const DEFAULT_LOG_RETENTION = RetentionDays.TWO_WEEKS;
 // Smallest valid (cpu, memory) pair on the Fargate matrix — must move together.
 export const DEFAULT_FARGATE_CPU = 256;
 export const DEFAULT_FARGATE_MEMORY_MIB = 512;

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

@@ -1,5 +1,6 @@
 import { FargateTaskDefinition, Ec2TaskDefinition, NetworkMode, type ContainerDefinition } from "aws-cdk-lib/aws-ecs";
 import type { Construct } from "constructs";
+import type { ILogGroup } from "aws-cdk-lib/aws-logs";
 import { type Role } from "aws-cdk-lib/aws-iam";
 import type { EcsConstructContext } from "./ecsContext.js";
 import type { EcsClusterProps, EcsServiceProps, EcsCapacityProvider } from "./ecsTypes.js";
@@ -52,4 +53,5 @@ export declare function createMigrationTaskDefinition(scope: Construct, id: stri
 export declare function addContainersToTask(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps, taskDefinition: FargateTaskDefinition | Ec2TaskDefinition): {
     containers: ContainerDefinition[];
     primaryContainer?: ContainerDefinition;
+    logGroup: ILogGroup;
 };

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

@@ -1,10 +1,11 @@
 import { AwsLogDriver, ContainerDependencyCondition, FargateTaskDefinition, Ec2TaskDefinition, NetworkMode, CpuArchitecture, OperatingSystemFamily } from "aws-cdk-lib/aws-ecs";
-import { Duration } from "aws-cdk-lib";
+import { Duration, RemovalPolicy } from "aws-cdk-lib";
 import { Secret as EcsSecret } from "aws-cdk-lib/aws-ecs";
 import { StringParameter } from "aws-cdk-lib/aws-ssm";
 import { resolveOrgId } from "../../../utils/cdkContext.js";
 import { validateSsmPathComponent } from "./ecsValidation.js";
-import { DEFAULT_LOG_RETENTION_DAYS, 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, DEFAULT_EC2_CONTAINER_MEMORY_MIB } from "./ecsConstants.js";
+import { LogGroup } from "../logging/logGroup.js";
 import { getContainerImage } from "./ecsImages.js";
 import { resolveRemoteConnections } from "./ecsRemoteConnections.js";
 import { resolveImportedSecret } from "../secrets/index.js";
@@ -124,6 +125,14 @@ export function addContainersToTask(ctx, serviceName, serviceProps, taskDefiniti
     const orgId = resolveOrgId(ctx.scope.node);
     const remoteEnvByService = resolveRemoteConnections([serviceProps], ctx.scope, orgId);
     const remoteEnv = remoteEnvByService[serviceName] ?? {};
+    // Explicit so the cluster can attach metric filters (createLogPatternAlarms).
+    // No logGroupName: CDK auto-names from the logical ID so it cannot collide
+    // with the orphaned-retained old group during the implicit→explicit replace.
+    // RETAIN (never DESTROY): preserves fail-closed evidence and supports rollback.
+    const logGroup = new LogGroup(ctx.scope, `${ctx.props.clusterName}${serviceName}LogGroup`, {
+        retention: DEFAULT_LOG_RETENTION,
+        removalPolicy: RemovalPolicy.RETAIN
+    });
     for (const containerConfig of serviceProps.containers) {
         const image = getContainerImage(ctx, serviceName, containerConfig, serviceProps);
         const isFirstWithPort = !primaryContainer && containerConfig.port !== undefined;
@@ -156,7 +165,7 @@ export function addContainersToTask(ctx, serviceName, serviceProps, taskDefiniti
             containerName: containerConfig.name,
             logging: new AwsLogDriver({
                 streamPrefix: `/ecs/${ctx.props.clusterName}/${serviceName}`,
-                logRetention: DEFAULT_LOG_RETENTION_DAYS
+                logGroup
             }),
             // remoteEnv (cross-app `${PREFIX}_HOST/_PORT`) intentionally overrides user
             // values — a stale manual setting must not mask the resolved peer.
@@ -250,5 +259,5 @@ export function addContainersToTask(ctx, serviceName, serviceProps, taskDefiniti
             });
         }
     }
-    return { containers, primaryContainer };
+    return { containers, primaryContainer, logGroup };
 }

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

@@ -19,7 +19,8 @@ import { type RemoteConnectionSpec } from "./ecsRemoteConnections.js";
 import { type SecretImport } from "../secrets/index.js";
 import type { ManagedDomainExports } from "../../../utils/domainTypes.js";
 import type { ITopic } from "aws-cdk-lib/aws-sns";
-import type { EcsServiceAlarmThresholds } from "../monitoring/index.js";
+import type { ILogGroup } from "aws-cdk-lib/aws-logs";
+import type { EcsServiceAlarmThresholds, LogPatternAlarmSpec } from "../monitoring/index.js";
 import { type Ec2InstancePersistentDataVolumeConfig } from "./ec2.js";
 export declare enum Protocol {
     HTTP = 0,
@@ -437,6 +438,19 @@ export interface EcsServiceProps {
      * - object: override specific thresholds
      */
     alarms?: EcsServiceAlarmThresholds | false;
+    /**
+     * Log-pattern alarms for this service's log group. Each spec creates a
+     * CloudWatch metric filter + alarm (see `createLogPatternAlarms`). Materialised
+     * only when the cluster carries `alertsTopic` and `alarms !== false` — the same
+     * gate as the per-service metric alarms.
+     */
+    logAlarms?: LogPatternAlarmSpec[];
+    /**
+     * Default CloudWatch metric namespace for this service's `logAlarms`. Each
+     * spec may override it per-entry, so one service can emit alarms in different
+     * namespaces (e.g. `Fjall/WebApp` for RLS, `Fjall/ClickHouse` for stuck-merge).
+     */
+    logMetricNamespace?: string;
     /**
      * Deployment circuit breaker policy.
      * - undefined (default): `{ enable: true, rollback: true }`
@@ -543,4 +557,6 @@ export interface ServiceData {
     primaryContainer?: ContainerDefinition;
     targetGroup?: IApplicationTargetGroup;
     scalingPolicy?: TargetTrackingScalingPolicy | StepScalingPolicy;
+    /** Explicit log group shared by all of the service's containers. */
+    logGroup: ILogGroup;
 }

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

@@ -12,6 +12,13 @@ import type { EcsClusterProps } from "./ecsTypes.js";
  * layer consumers never see a `migrations` field, so duplicating the
  * validation here would be unreachable.
  *
+ * Same applies to `service.awaitMigrationsFrom`: it is a patterns-layer
+ * cross-service ordering knob, resolved into a `node.addDependency(...)` edge
+ * (`wireServiceMigrationDependencies` in `computeEcs.ts`) BEFORE reaching the
+ * resources layer. It is not a field on `EcsServiceProps`, so a direct
+ * `new EcsCluster(...)` consumer cannot pass it — there is no resources-layer
+ * code path to validate.
+ *
  * @param props - The cluster props to validate
  * @throws Error if validation fails
  */

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

@@ -13,6 +13,13 @@ import { ScalingType } from "./ecsTypes.js";
  * layer consumers never see a `migrations` field, so duplicating the
  * validation here would be unreachable.
  *
+ * Same applies to `service.awaitMigrationsFrom`: it is a patterns-layer
+ * cross-service ordering knob, resolved into a `node.addDependency(...)` edge
+ * (`wireServiceMigrationDependencies` in `computeEcs.ts`) BEFORE reaching the
+ * resources layer. It is not a field on `EcsServiceProps`, so a direct
+ * `new EcsCluster(...)` consumer cannot pass it — there is no resources-layer
+ * code path to validate.
+ *
  * @param props - The cluster props to validate
  * @throws Error if validation fails
  */
@@ -94,6 +101,9 @@ export function validateEcsClusterProps(props) {
             if (max !== undefined && (max < 100 || max > 200)) {
                 throw new Error(`Service '${service.name}': deployment.maxHealthyPercent must be between 100 and 200 (got ${max}).`);
             }
+            if (min !== undefined && max !== undefined && min > max) {
+                throw new Error(`Service '${service.name}': deployment.minHealthyPercent (${min}) must be <= maxHealthyPercent (${max}).`);
+            }
             if (min === 100 && max === 100) {
                 throw new Error(`Service '${service.name}': deployment.minHealthyPercent and maxHealthyPercent cannot both be 100 ` +
                     "(no capacity to drain or expand — deploys would never roll forward).");

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

@@ -3,12 +3,12 @@ import { SingletonFunction as singletonFunction, Function, Code, Architecture, F
 import { FactName } from "aws-cdk-lib/region-info";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
 import { SqsEventSource, DynamoEventSource, S3EventSource } from "aws-cdk-lib/aws-lambda-event-sources";
 import { EventType } from "aws-cdk-lib/aws-s3";
 import { PolicyStatement, Effect } from "aws-cdk-lib/aws-iam";
 import { RetentionDays } from "aws-cdk-lib/aws-logs";
 import { LogGroup } from "../logging/logGroup.js";
-import { v4 as uuid } from "uuid";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 import { resolveImportedSecret } from "../secrets/index.js";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
@@ -65,11 +65,29 @@ const SECRETS_EXTENSION = {
  * mis-tune alarms relative to runtime behaviour.
  */
 const LAMBDA_DEFAULT_TIMEOUT_SECONDS = 300;
+/**
+ * Stable, deterministic uuid for a SingletonFunction so its logical ID
+ * (`SingletonLambda${uuid-without-dashes}`) does not drift across synths. A
+ * random default would recreate the singleton — and re-run any custom resource
+ * fronted by it — on every deploy.
+ */
+function deriveStableSingletonUuid(scope, id) {
+    const hash = createHash("sha256")
+        .update(`${scope.node.path}/${id}`)
+        .digest("hex");
+    return [
+        hash.slice(0, 8),
+        hash.slice(8, 12),
+        hash.slice(12, 16),
+        hash.slice(16, 20),
+        hash.slice(20, 32)
+    ].join("-");
+}
 export class SingletonFunction extends singletonFunction {
     constructor(scope, id, props) {
         super(scope, id, {
             ...props,
-            uuid: props.uuid ?? uuid(),
+            uuid: props.uuid ?? deriveStableSingletonUuid(scope, id),
             timeout: Duration.seconds(props.timeout ?? LAMBDA_DEFAULT_TIMEOUT_SECONDS),
             description: props.lambdaDescription ?? `${id} singleton lambda`,
             runtime: props.runtime,

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

@@ -1,6 +1,7 @@
 import { Duration } from "aws-cdk-lib";
 import { Connections, type IConnectable, type IVpc } from "aws-cdk-lib/aws-ec2";
 import { type IInstanceEngine } from "aws-cdk-lib/aws-rds";
+import { type IGrantable, type Grant } from "aws-cdk-lib/aws-iam";
 import { Construct } from "constructs";
 import { SecurityGroup } from "../networking/securityGroup.js";
 import { Secret } from "../secrets/index.js";
@@ -31,6 +32,15 @@ interface RdsProps {
     encryption?: EncryptionConfig;
     publiclyAccessible?: boolean;
     deletionProtection?: boolean;
+    /**
+     * Enable RDS IAM database authentication on the instance. Opt-in; defaults to
+     * off (undefined → CDK omits the property, leaving existing consumers' synth
+     * unchanged). When true, IAM principals granted via {@link grantIamConnect}
+     * connect with short-lived `rds-db:connect` tokens instead of a stored
+     * password — password auth keeps working in parallel. See ADR
+     * decisions/2026-06-17-rls-role-auth-and-launch-gating.md.
+     */
+    iamAuthentication?: boolean;
     /** ARN or identifier of DB instance snapshot to restore from */
     snapshotIdentifier?: string;
     /** Username from the snapshot (required when restoring from snapshot to reset password) */
@@ -70,6 +80,15 @@ export declare class RdsInstance extends Construct implements IConnectable {
     }>;
     getDatabaseName(): string;
     getConnectionString(): string;
+    /**
+     * Grant an IAM principal permission to connect as `dbUsername` via RDS IAM
+     * database authentication. Requires the instance to be created with
+     * `iamAuthentication: true`. Delegates to the L2 `grantConnect`, which scopes
+     * `rds-db:connect` to the exact `dbuser:<dbiResourceId>/<dbUsername>` ARN —
+     * never a bare wildcard. See ADR
+     * decisions/2026-06-17-rls-role-auth-and-launch-gating.md.
+     */
+    grantIamConnect(grantee: IGrantable, dbUsername: string): Grant;
     static build(id: string, props: RdsProps): (sb: StackBuilder) => Construct;
 }
 export {};

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

@@ -136,7 +136,8 @@ export class RdsInstance extends Construct {
             deletionProtection: props.deletionProtection ?? true,
             preferredMaintenanceWindow: props.preferredMaintenanceWindow ??
                 RDS_DEFAULTS.PREFERRED_MAINTENANCE_WINDOW,
-            publiclyAccessible: props.publiclyAccessible ?? false
+            publiclyAccessible: props.publiclyAccessible ?? false,
+            iamAuthentication: props.iamAuthentication
         };
         if (props.snapshotIdentifier) {
             // Create from snapshot
@@ -328,6 +329,17 @@ exports.handler = async (event) => {
     getConnectionString() {
         return `${this.engineConfig.family}://${this.getHostEndpoint()}:${this.getHostPort()}/${this.getDatabaseName()}`;
     }
+    /**
+     * Grant an IAM principal permission to connect as `dbUsername` via RDS IAM
+     * database authentication. Requires the instance to be created with
+     * `iamAuthentication: true`. Delegates to the L2 `grantConnect`, which scopes
+     * `rds-db:connect` to the exact `dbuser:<dbiResourceId>/<dbUsername>` ARN —
+     * never a bare wildcard. See ADR
+     * decisions/2026-06-17-rls-role-auth-and-launch-gating.md.
+     */
+    grantIamConnect(grantee, dbUsername) {
+        return this.database.grantConnect(grantee, dbUsername);
+    }
     static build(id, props) {
         return (sb) => {
             const newProps = {

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

@@ -29,32 +29,27 @@ export interface ClickHouseAlarmsProps {
     asgName: string;
     alarmTopic: ITopic;
     /**
-     * Webapp log group. Required to wire the stuck-merge alarm — `client.ts`
-     * emits `serverLogger.warn("ClickHouse", "Stuck merge detected")` when
-     * `system.merges` shows a merge elapsed > 30 min.
-     */
-    webappLogGroup: ILogGroup;
-    /**
-     * Backup-task log group. Required to wire the backup-failure alarm —
+     * Backup-task log group. When present, wires the backup-failure alarm —
      * `BACKUP DATABASE … TO S3(…)` emits `AccessDenied` / `S3Exception` lines
      * when the IAM grant or bucket policy is misconfigured (silent before the
      * alarm landed; the daily backup task exited non-zero with no signal).
+     * Omitted when `backupSchedule: false` — no backup task, no log group.
      */
-    backupTaskLogGroup: ILogGroup;
+    backupTaskLogGroup?: ILogGroup;
     config?: ClickHouseAlarmThresholds;
 }
 /**
- * Single-node ClickHouse posture alarms. Covers host-level CPU + (optional)
- * memory and disk via the CloudWatch Agent metric namespace `CWAgent`, plus
- * two log-driven alarms:
+ * Single-node ClickHouse host-posture alarms. Covers host-level CPU + (optional)
+ * memory and disk via the CloudWatch Agent metric namespace `CWAgent`, plus the
+ * backup-failure log alarm when a backup-task log group is supplied:
  *
- * - **Stuck merges** — `client.ts` polls `system.merges` every 5 min and logs
- *   `serverLogger.warn("ClickHouse", "Stuck merge detected")` when elapsed
- *   exceeds 30 min. The metric filter on the webapp log group emits a count
- *   metric per match; the alarm fires on Sum >= 1 over 5 min × 2 evaluations.
  * - **Backup failures** — `AccessDenied` or `S3Exception` from the backup
  *   task's BACKUP DATABASE TO S3 statement. Closes the silent-failure mode
  *   that masked the original IAM-grant misconfiguration (see
  *   `designs/2026-04-27-clickhouse-backup-iam-role.md`).
+ *
+ * The stuck-merge alarm — a `"Stuck merge detected"` line emitted by the webapp
+ * app process, not this construct — lives on the app service's declarative
+ * `logAlarms` instead; it is an app-log alarm, not a database-host concern.
  */
 export declare function createClickHouseAlarms(props: ClickHouseAlarmsProps): Alarm[];

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

@@ -4,23 +4,23 @@ import { SnsAction } from "aws-cdk-lib/aws-cloudwatch-actions";
 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";
-const CLICKHOUSE_METRIC_NAMESPACE = "Fjall/ClickHouse";
+import { METRIC_NAMESPACE } from "./metricNamespaces.js";
 /**
- * Single-node ClickHouse posture alarms. Covers host-level CPU + (optional)
- * memory and disk via the CloudWatch Agent metric namespace `CWAgent`, plus
- * two log-driven alarms:
+ * Single-node ClickHouse host-posture alarms. Covers host-level CPU + (optional)
+ * memory and disk via the CloudWatch Agent metric namespace `CWAgent`, plus the
+ * backup-failure log alarm when a backup-task log group is supplied:
  *
- * - **Stuck merges** — `client.ts` polls `system.merges` every 5 min and logs
- *   `serverLogger.warn("ClickHouse", "Stuck merge detected")` when elapsed
- *   exceeds 30 min. The metric filter on the webapp log group emits a count
- *   metric per match; the alarm fires on Sum >= 1 over 5 min × 2 evaluations.
  * - **Backup failures** — `AccessDenied` or `S3Exception` from the backup
  *   task's BACKUP DATABASE TO S3 statement. Closes the silent-failure mode
  *   that masked the original IAM-grant misconfiguration (see
  *   `designs/2026-04-27-clickhouse-backup-iam-role.md`).
+ *
+ * The stuck-merge alarm — a `"Stuck merge detected"` line emitted by the webapp
+ * app process, not this construct — lives on the app service's declarative
+ * `logAlarms` instead; it is an app-log alarm, not a database-host concern.
  */
 export function createClickHouseAlarms(props) {
-    const { scope, instanceRole, asgName, alarmTopic, webappLogGroup, backupTaskLogGroup, config = {} } = props;
+    const { scope, instanceRole, asgName, alarmTopic, backupTaskLogGroup, config = {} } = props;
     const alarms = [];
     const snsAction = new SnsAction(alarmTopic);
     const cpuAlarm = new Alarm(scope, "ClickHouseCpuAlarm", {
@@ -87,53 +87,31 @@ export function createClickHouseAlarms(props) {
         treatMissingData: TreatMissingData.NOT_BREACHING
     });
     registerAlarm(diskCriticalAlarm, snsAction, alarms);
-    const stuckMergeMetricName = "ClickHouseStuckMergeCount";
-    new MetricFilter(scope, "ClickHouseStuckMergeMetricFilter", {
-        logGroup: webappLogGroup,
-        metricNamespace: CLICKHOUSE_METRIC_NAMESPACE,
-        metricName: stuckMergeMetricName,
-        filterPattern: FilterPattern.literal('"Stuck merge detected"'),
-        metricValue: "1",
-        defaultValue: 0
-    });
-    const stuckMergeAlarm = new Alarm(scope, "ClickHouseStuckMergeAlarm", {
-        alarmDescription: buildAlarmDescription("ClickHouse merge stuck > 30 min — investigate parts pressure or replica health", undefined),
-        metric: new Metric({
-            namespace: CLICKHOUSE_METRIC_NAMESPACE,
-            metricName: stuckMergeMetricName,
-            period: Duration.minutes(5),
-            statistic: "Sum"
-        }),
-        threshold: 1,
-        evaluationPeriods: 2,
-        datapointsToAlarm: 2,
-        comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
-        treatMissingData: TreatMissingData.NOT_BREACHING
-    });
-    registerAlarm(stuckMergeAlarm, snsAction, alarms);
-    const backupFailureMetricName = "ClickHouseBackupFailureCount";
-    new MetricFilter(scope, "ClickHouseBackupFailureMetricFilter", {
-        logGroup: backupTaskLogGroup,
-        metricNamespace: CLICKHOUSE_METRIC_NAMESPACE,
-        metricName: backupFailureMetricName,
-        filterPattern: FilterPattern.anyTerm("AccessDenied", "S3Exception"),
-        metricValue: "1",
-        defaultValue: 0
-    });
-    const backupFailureAlarm = new Alarm(scope, "ClickHouseBackupFailureAlarm", {
-        alarmDescription: buildAlarmDescription(`ClickHouse BACKUP TO S3 emitted AccessDenied/S3Exception — verify instance role '${instanceRole.roleName}' grant on backup bucket`, undefined),
-        metric: new Metric({
-            namespace: CLICKHOUSE_METRIC_NAMESPACE,
+    if (backupTaskLogGroup !== undefined) {
+        const backupFailureMetricName = "ClickHouseBackupFailureCount";
+        new MetricFilter(scope, "ClickHouseBackupFailureMetricFilter", {
+            logGroup: backupTaskLogGroup,
+            metricNamespace: METRIC_NAMESPACE.CLICKHOUSE,
             metricName: backupFailureMetricName,
-            period: Duration.hours(1),
-            statistic: "Sum"
-        }),
-        threshold: 1,
-        evaluationPeriods: 1,
-        datapointsToAlarm: 1,
-        comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
-        treatMissingData: TreatMissingData.NOT_BREACHING
-    });
-    registerAlarm(backupFailureAlarm, snsAction, alarms);
+            filterPattern: FilterPattern.anyTerm("AccessDenied", "S3Exception"),
+            metricValue: "1",
+            defaultValue: 0
+        });
+        const backupFailureAlarm = new Alarm(scope, "ClickHouseBackupFailureAlarm", {
+            alarmDescription: buildAlarmDescription(`ClickHouse BACKUP TO S3 emitted AccessDenied/S3Exception — verify instance role '${instanceRole.roleName}' grant on backup bucket`, undefined),
+            metric: new Metric({
+                namespace: METRIC_NAMESPACE.CLICKHOUSE,
+                metricName: backupFailureMetricName,
+                period: Duration.hours(1),
+                statistic: "Sum"
+            }),
+            threshold: 1,
+            evaluationPeriods: 1,
+            datapointsToAlarm: 1,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+            treatMissingData: TreatMissingData.NOT_BREACHING
+        });
+        registerAlarm(backupFailureAlarm, snsAction, alarms);
+    }
     return alarms;
 }

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

@@ -43,7 +43,11 @@ export function createEcsServiceAlarms(props) {
             evaluationPeriods: 2,
             datapointsToAlarm: 2,
             comparisonOperator: ComparisonOperator.LESS_THAN_THRESHOLD,
-            treatMissingData: TreatMissingData.BREACHING
+            // RunningTaskCount (Container Insights) is sparse, so missing data must
+            // not breach — otherwise metric gaps false-alarm healthy services and
+            // scaled-to-zero workers alarm permanently. A real count < threshold
+            // still fires.
+            treatMissingData: TreatMissingData.NOT_BREACHING
         });
         registerAlarm(runningTasksAlarm, snsAction, alarms);
     }

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

@@ -4,3 +4,5 @@ export { createRdsAlarms, type RdsAlarmThresholds, type RdsAlarmsProps } from ".
 export { createLambdaAlarms, type LambdaAlarmThresholds, type LambdaAlarmsProps } from "./lambdaAlarms.js";
 export { createScheduleAlarms, type ScheduleAlarmThresholds, type CreateScheduleAlarmsProps } from "./scheduleAlarms.js";
 export { createClickHouseAlarms, type ClickHouseAlarmThresholds, type ClickHouseAlarmsProps } from "./clickhouseAlarms.js";
+export { createLogPatternAlarms, type LogPatternAlarmSpec, type LogPatternAlarmsProps } from "./logPatternAlarms.js";
+export { METRIC_NAMESPACE, type MetricNamespace } from "./metricNamespaces.js";

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

@@ -4,3 +4,5 @@ export { createRdsAlarms } from "./rdsAlarms.js";
 export { createLambdaAlarms } from "./lambdaAlarms.js";
 export { createScheduleAlarms } from "./scheduleAlarms.js";
 export { createClickHouseAlarms } from "./clickhouseAlarms.js";
+export { createLogPatternAlarms } from "./logPatternAlarms.js";
+export { METRIC_NAMESPACE } from "./metricNamespaces.js";

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

@@ -0,0 +1,55 @@
+import { Duration } from "aws-cdk-lib";
+import { Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { type ILogGroup } from "aws-cdk-lib/aws-logs";
+import type { ITopic } from "aws-cdk-lib/aws-sns";
+import type { Construct } from "constructs";
+/**
+ * One log-pattern alarm: a CloudWatch metric filter over a log group plus the
+ * alarm that fires when the pattern is matched. Declarative — callers describe
+ * the match with plain strings; the raw CDK `FilterPattern` is built inside the
+ * primitive, so the spec never leaks raw CDK at the call site.
+ *
+ * Exactly one of `literal` / `anyTerms` must be set.
+ */
+export interface LogPatternAlarmSpec {
+    /** Stable logical-ID stem; the MetricFilter + Alarm derive their construct IDs from it. */
+    idStem: string;
+    /** CloudWatch metric name emitted by the filter and read by the alarm. */
+    metricName: string;
+    /** Responder-facing alarm description (the applicationId tag is appended automatically). */
+    description: string;
+    /** Match this exact CloudWatch Logs filter pattern (e.g. `'"Stuck merge detected"'`). */
+    literal?: string;
+    /** Match if ANY of these terms appears (CloudWatch Logs OR semantics). */
+    anyTerms?: string[];
+    /** Metric namespace for this spec; falls back to the props-level default. */
+    metricNamespace?: string;
+    /** Sum-over-period threshold the alarm fires at. Default 1 (first match). */
+    threshold?: number;
+    /** Metric period. Default 1 minute (fast fail-closed detection). */
+    period?: Duration;
+    /** Consecutive periods evaluated. Default 1. */
+    evaluationPeriods?: number;
+    /** Datapoints within the window that must breach. Default = evaluationPeriods. */
+    datapointsToAlarm?: number;
+}
+export interface LogPatternAlarmsProps {
+    scope: Construct;
+    /** Log group the metric filters attach to. */
+    logGroup: ILogGroup;
+    /** SNS topic alarms notify on both ALARM and OK transitions. */
+    alarmTopic: ITopic;
+    /** Default metric namespace for specs that do not override it per-entry. */
+    metricNamespace?: string;
+    /** The alarms to create. */
+    specs: LogPatternAlarmSpec[];
+    /** Application ID for webhook-to-application alarm mapping. */
+    applicationId?: string;
+}
+/**
+ * Create CloudWatch log-pattern alarms — a MetricFilter + Alarm per spec —
+ * wired to the SNS topic. Sibling to `createEcsServiceAlarms`: same conventions
+ * (`registerAlarm` for ALARM+OK actions, applicationId tagging via
+ * `tagAlarmsWithApplicationId`). Reusable across every factory consumer.
+ */
+export declare function createLogPatternAlarms(props: LogPatternAlarmsProps): Alarm[];

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

@@ -0,0 +1,74 @@
+import { Duration } from "aws-cdk-lib";
+import { Alarm, ComparisonOperator, Metric, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+import { SnsAction } from "aws-cdk-lib/aws-cloudwatch-actions";
+import { FilterPattern, MetricFilter } from "aws-cdk-lib/aws-logs";
+import { buildAlarmDescription, registerAlarm, tagAlarmsWithApplicationId } from "./alarmDefaults.js";
+/**
+ * Validate a spec carries exactly one matcher, a usable id stem, and a
+ * resolvable namespace; return the built filter pattern + resolved namespace.
+ * Throws (not a `Result`) — this is synth-time CDK construction, where a
+ * malformed spec must fail the synth loudly rather than emit a dead alarm.
+ */
+function resolveSpec(spec, defaultNamespace) {
+    if (spec.idStem.trim() === "") {
+        throw new Error("logPatternAlarm spec requires a non-empty idStem");
+    }
+    const hasLiteral = spec.literal !== undefined;
+    const hasAnyTerms = spec.anyTerms !== undefined;
+    if (hasLiteral === hasAnyTerms) {
+        throw new Error(`logPatternAlarm spec '${spec.idStem}' must set exactly one of 'literal' or 'anyTerms'`);
+    }
+    if (hasAnyTerms &&
+        spec.anyTerms !== undefined &&
+        spec.anyTerms.length === 0) {
+        throw new Error(`logPatternAlarm spec '${spec.idStem}' has an empty 'anyTerms' array`);
+    }
+    const namespace = spec.metricNamespace ?? defaultNamespace;
+    if (namespace === undefined || namespace.trim() === "") {
+        throw new Error(`logPatternAlarm spec '${spec.idStem}' has no metric namespace — set spec.metricNamespace or props.metricNamespace`);
+    }
+    const filterPattern = spec.literal !== undefined
+        ? FilterPattern.literal(spec.literal)
+        : FilterPattern.anyTerm(...(spec.anyTerms ?? []));
+    return { filterPattern, namespace };
+}
+/**
+ * Create CloudWatch log-pattern alarms — a MetricFilter + Alarm per spec —
+ * wired to the SNS topic. Sibling to `createEcsServiceAlarms`: same conventions
+ * (`registerAlarm` for ALARM+OK actions, applicationId tagging via
+ * `tagAlarmsWithApplicationId`). Reusable across every factory consumer.
+ */
+export function createLogPatternAlarms(props) {
+    const { scope, logGroup, alarmTopic, metricNamespace, specs, applicationId } = props;
+    const alarms = [];
+    const snsAction = new SnsAction(alarmTopic);
+    for (const spec of specs) {
+        const { filterPattern, namespace } = resolveSpec(spec, metricNamespace);
+        new MetricFilter(scope, `${spec.idStem}MetricFilter`, {
+            logGroup,
+            metricNamespace: namespace,
+            metricName: spec.metricName,
+            filterPattern,
+            metricValue: "1",
+            defaultValue: 0
+        });
+        const evaluationPeriods = spec.evaluationPeriods ?? 1;
+        const alarm = new Alarm(scope, `${spec.idStem}Alarm`, {
+            alarmDescription: buildAlarmDescription(spec.description, applicationId),
+            metric: new Metric({
+                namespace,
+                metricName: spec.metricName,
+                period: spec.period ?? Duration.minutes(1),
+                statistic: "Sum"
+            }),
+            threshold: spec.threshold ?? 1,
+            evaluationPeriods,
+            datapointsToAlarm: spec.datapointsToAlarm ?? evaluationPeriods,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+            treatMissingData: TreatMissingData.NOT_BREACHING
+        });
+        registerAlarm(alarm, snsAction, alarms);
+    }
+    tagAlarmsWithApplicationId(alarms, applicationId);
+    return alarms;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Single source of truth for Fjall CloudWatch metric namespaces.
+ *
+ * Log-pattern metric filters and their alarms read from these namespaces. The
+ * webapp app service declares RLS alarms under `WEBAPP` and relocates the
+ * ClickHouse stuck-merge alarm under `CLICKHOUSE` (the log line is app-emitted,
+ * so it is an app-log alarm carrying a database-domain namespace).
+ */
+export declare const METRIC_NAMESPACE: {
+    readonly CLICKHOUSE: "Fjall/ClickHouse";
+    readonly WEBAPP: "Fjall/WebApp";
+};
+export type MetricNamespace = (typeof METRIC_NAMESPACE)[keyof typeof METRIC_NAMESPACE];

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

@@ -0,0 +1,12 @@
+/**
+ * Single source of truth for Fjall CloudWatch metric namespaces.
+ *
+ * Log-pattern metric filters and their alarms read from these namespaces. The
+ * webapp app service declares RLS alarms under `WEBAPP` and relocates the
+ * ClickHouse stuck-merge alarm under `CLICKHOUSE` (the log line is app-emitted,
+ * so it is an app-log alarm carrying a database-domain namespace).
+ */
+export const METRIC_NAMESPACE = {
+    CLICKHOUSE: "Fjall/ClickHouse",
+    WEBAPP: "Fjall/WebApp"
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "2.17.0",
+  "version": "2.18.0",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
@@ -53,7 +53,6 @@
     "@peculiar/x509": "1.14.0",
     "@types/aws-lambda": "^8.10.161",
     "@types/node": "^25.6.0",
-    "@types/uuid": "^11.0.0",
     "@typescript-eslint/eslint-plugin": "^8.59.1",
     "@typescript-eslint/parser": "^8.59.1",
     "eslint": "^10.2.1",
@@ -63,10 +62,9 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1038.0",
-    "@fjall/generator": "^2.17.0",
-    "@fjall/util": "^2.17.0",
-    "constructs": "^10.0.0",
-    "uuid": "^14.0.0"
+    "@fjall/generator": "^2.18.0",
+    "@fjall/util": "^2.18.0",
+    "constructs": "^10.0.0"
   },
   "overrides": {
     "@smithy/core": "2.5.5"
@@ -79,5 +77,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "gitHead": "21cfe1aae339e12183af2813ec81f581b9b77d49"
+  "gitHead": "37008ca5469398c42a09e6babc8cc4192ab938b2"
 }