@fjall/components-infrastructure 0.96.0 → 0.99.1

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

@@ -1,21 +1,37 @@
-import { SQSQueue } from "../../resources/aws/messaging/sqs.js";
+import { EventBus as CdkEventBus } from "aws-cdk-lib/aws-events";
+import { SQSQueue, SQS_LIMITS } from "../../resources/aws/messaging/sqs.js";
 import { SNSTopic } from "../../resources/aws/messaging/sns.js";
 import { EventBridgeBus } from "../../resources/aws/messaging/eventbridge.js";
+import { Subscription } from "../../resources/aws/messaging/subscription.js";
 import { FjallLogger } from "../../utils/validationLogger.js";
 /**
  * Validates SQS props and logs warnings for misconfigured options.
  */
 function validateSQSProps(props) {
-    // Validate visibility timeout range (0-43200 seconds = 12 hours)
     if (props.visibilityTimeout !== undefined &&
-        (props.visibilityTimeout < 0 || props.visibilityTimeout > 43200)) {
-        throw new Error("visibilityTimeout must be between 0 and 43200 seconds (12 hours)");
+        (props.visibilityTimeout < SQS_LIMITS.VISIBILITY_TIMEOUT.MIN_SECONDS ||
+            props.visibilityTimeout > SQS_LIMITS.VISIBILITY_TIMEOUT.MAX_SECONDS)) {
+        throw new Error(`visibilityTimeout must be between ${SQS_LIMITS.VISIBILITY_TIMEOUT.MIN_SECONDS} and ${SQS_LIMITS.VISIBILITY_TIMEOUT.MAX_SECONDS} seconds (12 hours)`);
     }
-    // Validate message retention period (60-1209600 seconds = 1 minute to 14 days)
     if (props.messageRetentionPeriod !== undefined &&
-        (props.messageRetentionPeriod < 60 ||
-            props.messageRetentionPeriod > 1209600)) {
-        throw new Error("messageRetentionPeriod must be between 60 and 1209600 seconds (1 minute to 14 days)");
+        (props.messageRetentionPeriod < SQS_LIMITS.MESSAGE_RETENTION.MIN_SECONDS ||
+            props.messageRetentionPeriod > SQS_LIMITS.MESSAGE_RETENTION.MAX_SECONDS)) {
+        throw new Error(`messageRetentionPeriod must be between ${SQS_LIMITS.MESSAGE_RETENTION.MIN_SECONDS} and ${SQS_LIMITS.MESSAGE_RETENTION.MAX_SECONDS} seconds (1 minute to 14 days)`);
+    }
+    if (props.deliveryDelay !== undefined &&
+        (props.deliveryDelay < SQS_LIMITS.DELAY.MIN_SECONDS ||
+            props.deliveryDelay > SQS_LIMITS.DELAY.MAX_SECONDS)) {
+        throw new Error(`deliveryDelay must be between ${SQS_LIMITS.DELAY.MIN_SECONDS} and ${SQS_LIMITS.DELAY.MAX_SECONDS} seconds (15 minutes)`);
+    }
+    if (props.receiveMessageWaitTime !== undefined &&
+        (props.receiveMessageWaitTime < SQS_LIMITS.RECEIVE_WAIT_TIME.MIN_SECONDS ||
+            props.receiveMessageWaitTime > SQS_LIMITS.RECEIVE_WAIT_TIME.MAX_SECONDS)) {
+        throw new Error(`receiveMessageWaitTime must be between ${SQS_LIMITS.RECEIVE_WAIT_TIME.MIN_SECONDS} and ${SQS_LIMITS.RECEIVE_WAIT_TIME.MAX_SECONDS} seconds (long-poll cap)`);
+    }
+    if (props.maxMessageSize !== undefined &&
+        (props.maxMessageSize < SQS_LIMITS.MESSAGE_SIZE.MIN_BYTES ||
+            props.maxMessageSize > SQS_LIMITS.MESSAGE_SIZE.MAX_BYTES)) {
+        throw new Error(`maxMessageSize must be between ${SQS_LIMITS.MESSAGE_SIZE.MIN_BYTES} and ${SQS_LIMITS.MESSAGE_SIZE.MAX_BYTES} bytes (256 KB)`);
     }
     // Warn about FIFO-specific options on standard queues
     if (props.queueType !== "fifo") {
@@ -58,6 +74,7 @@ export class QueueMessaging extends SQSQueue {
     /** The connector type for unified connection processing. */
     connectorType = "queue";
     constructor(scope, id, props) {
+        validateSQSProps(props);
         const queueProps = {
             queueType: props.queueType,
             visibilityTimeout: props.visibilityTimeout,
@@ -120,14 +137,8 @@ export class TopicMessaging extends SNSTopic {
     /** Type discriminator for runtime type narrowing. */
     messagingType = "topic";
     constructor(scope, id, props) {
-        const topicProps = {
-            topicName: props.topicName,
-            displayName: props.displayName,
-            fifo: props.fifo,
-            contentBasedDeduplication: props.contentBasedDeduplication,
-            removalPolicy: props.removalPolicy
-        };
-        super(scope, id, topicProps);
+        validateTopicProps(props);
+        super(scope, id, props);
     }
     /**
      * Grant publish permissions to the grantee.
@@ -151,12 +162,33 @@ export class TopicMessaging extends SNSTopic {
 export class EventBusMessaging extends EventBridgeBus {
     /** Type discriminator for runtime type narrowing. */
     messagingType = "eventBus";
+    /**
+     * Application name threaded into Subscription default descriptions when the
+     * caller does not supply one. Captured at construction so `subscribe(...)`
+     * has the same naming context as `App.addSchedule(...)`.
+     */
+    #appName;
+    /**
+     * Brand distinguishing app buses from the AWS-managed account+region default
+     * bus. Used by `subscribe(...)` to refuse `aws.*` source patterns on app
+     * buses (silent-no-op trap — AWS service events only fire on the default
+     * bus). Set by `fromAwsServiceBus(...)`; defaults to `false` for buses
+     * created via the regular constructor path or `fromEventBusArn(...)`.
+     */
+    #isAwsServiceBus;
     constructor(scope, id, props) {
         const eventBusProps = {
             eventBusName: props.eventBusName,
-            removalPolicy: props.removalPolicy
+            appName: props.appName,
+            description: props.description,
+            removalPolicy: props.removalPolicy,
+            importedBus: props.importedBus
         };
         super(scope, id, eventBusProps);
+        if (props.appName !== undefined) {
+            this.#appName = props.appName;
+        }
+        this.#isAwsServiceBus = props.awsServiceBus === true;
     }
     /**
      * Grant put events permissions to the grantee.
@@ -165,6 +197,70 @@ export class EventBusMessaging extends EventBridgeBus {
     grantPutEventsTo(grantee) {
         return this.getEventBus().grantPutEventsTo(grantee);
     }
+    /**
+     * Add a pub/sub subscription scoped to this bus. Threads the bus's
+     * `IEventBus` and the captured `appName` into the Subscription so the
+     * synthesised rule attaches to this bus (not the default AWS bus) and the
+     * default description picks up the bus's app context.
+     *
+     * Refuses `aws.*` source patterns when the wrapper is an app bus rather
+     * than the AWS-managed default bus. AWS service events fire only on the
+     * account+region default bus; subscribing them on a custom app bus
+     * synthesises and deploys cleanly but never invokes the target. Use
+     * `EventBusMessaging.fromAwsServiceBus(...)` to import the default bus
+     * for AWS service event traffic.
+     */
+    subscribe(id, props) {
+        if (!this.#isAwsServiceBus) {
+            const sources = props.pattern.source ?? [];
+            const awsSources = sources.filter((s) => typeof s === "string" && s.startsWith("aws."));
+            if (awsSources.length > 0) {
+                throw new Error(`Subscription '${id}' uses AWS service source(s) [${awsSources.join(", ")}] on a custom app event bus. AWS service events fire only on the account+region default bus; subscribing them on a custom bus deploys cleanly but never invokes the target. Use EventBusMessaging.fromAwsServiceBus(scope, id, region, account) instead of app.getEventBus().`);
+            }
+        }
+        return new Subscription(this, id, {
+            ...props,
+            eventBus: this.getEventBus(),
+            appName: props.appName ?? this.#appName
+        });
+    }
+    /**
+     * Wrap a bus imported from another account/region by ARN per D19. The
+     * returned handle supports `subscribe(...)` identically to created buses;
+     * rules are owned by the importing stack and attach to the imported bus's
+     * ARN. The base wrapper short-circuits resource creation when `importedBus`
+     * is set, so no `AWS::Events::EventBus` is synthesised and bus-level
+     * mutations (description, removalPolicy, CfnOutputs) are skipped.
+     */
+    static fromEventBusArn(scope, id, arn) {
+        const importedBus = CdkEventBus.fromEventBusArn(scope, `${id}Bus`, arn);
+        return new EventBusMessaging(scope, id, {
+            type: "eventBus",
+            importedBus
+        });
+    }
+    /**
+     * Wrap the AWS-managed account+region `default` event bus. This is the
+     * bus that receives `aws.*` service events emitted via CloudTrail
+     * (`aws.ecr` `CreateRepository`, `aws.ec2` state-change, etc.); custom
+     * Fjall app buses do not receive this traffic. The returned wrapper has
+     * the AWS-service brand set, so `subscribe(...)` accepts `aws.*` source
+     * patterns; subscribing app-source patterns is still allowed but
+     * unusual (the canonical app-source path is `app.getEventBus()`).
+     *
+     * @param region AWS region holding the default bus (typically the stack
+     * region — the default bus is per-account-per-region).
+     * @param account AWS account id holding the default bus.
+     */
+    static fromAwsServiceBus(scope, id, region, account) {
+        const arn = `arn:aws:events:${region}:${account}:event-bus/default`;
+        const importedBus = CdkEventBus.fromEventBusArn(scope, `${id}Bus`, arn);
+        return new EventBusMessaging(scope, id, {
+            type: "eventBus",
+            importedBus,
+            awsServiceBus: true
+        });
+    }
 }
 /**
  * Factory for creating messaging resources.
@@ -209,10 +305,8 @@ export class MessagingFactory {
         return (_app, scope) => {
             switch (props.type) {
                 case "queue":
-                    validateSQSProps(props);
                     return new QueueMessaging(scope, id, props);
                 case "topic":
-                    validateTopicProps(props);
                     return new TopicMessaging(scope, id, props);
                 case "eventBus":
                     return new EventBusMessaging(scope, id, props);
@@ -224,5 +318,6 @@ export class MessagingFactory {
         };
     }
 }
-// Re-export type guards
+// Canonical D18(b) re-export — pinned by subscription.test.ts integrity suite.
+export { EventField, RuleTargetInput } from "aws-cdk-lib/aws-events";
 export { isQueueMessaging, isTopicMessaging, isEventBusMessaging } from "./interfaces/messaging.js";

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

@@ -1,5 +1,5 @@
 import { Construct } from "constructs";
-import { Vpc } from "../../resources/aws/networking/vpc.js";
+import { DEFAULT_MAX_AZS, Vpc } from "../../resources/aws/networking/vpc.js";
 import { FjallLogger } from "../../utils/validationLogger.js";
 function validateNetworkProps(props) {
     if (props.maxAzs !== undefined && (props.maxAzs < 1 || props.maxAzs > 3)) {
@@ -8,7 +8,7 @@ function validateNetworkProps(props) {
     if (typeof props.natGateways === "object" &&
         props.natGateways !== null &&
         props.natGateways.count !== undefined) {
-        const maxAzs = props.maxAzs ?? 3;
+        const maxAzs = props.maxAzs ?? DEFAULT_MAX_AZS;
         if (props.natGateways.count > maxAzs) {
             FjallLogger.warn(`'natGateways.count' (${props.natGateways.count}) exceeds maxAzs (${maxAzs}).`);
         }
@@ -20,7 +20,6 @@ function validateNetworkProps(props) {
 export class NetworkFactory {
     static build(id, props) {
         return (app, scope) => {
-            validateNetworkProps(props);
             return new Network(scope, id, props, app);
         };
     }
@@ -29,15 +28,25 @@ export class Network extends Construct {
     vpc;
     constructor(scope, id, props, app) {
         super(scope, id);
+        validateNetworkProps(props);
         this.vpc = this.createVpc(id, props, app);
     }
     createVpc(id, props, app) {
         const rawAccountId = app.node.tryGetContext("accountId");
-        const accountId = (typeof rawAccountId === "string" ? rawAccountId : undefined) ||
-            process.env.CDK_DEFAULT_ACCOUNT;
-        const region = process.env.CDK_DEFAULT_REGION;
+        const guardedCtxAccountId = typeof rawAccountId === "string" && rawAccountId !== ""
+            ? rawAccountId
+            : undefined;
+        const envAccountId = process.env.CDK_DEFAULT_ACCOUNT;
+        const accountId = guardedCtxAccountId ??
+            (envAccountId !== undefined && envAccountId !== ""
+                ? envAccountId
+                : undefined);
+        const envRegion = process.env.CDK_DEFAULT_REGION;
+        const region = envRegion !== undefined && envRegion !== "" ? envRegion : undefined;
         const rawIpamPoolId = app.node.tryGetContext("ipamPoolId");
-        const ipv4IpamPoolId = typeof rawIpamPoolId === "string" ? rawIpamPoolId : undefined;
+        const ipv4IpamPoolId = typeof rawIpamPoolId === "string" && rawIpamPoolId !== ""
+            ? rawIpamPoolId
+            : undefined;
         const vpcProps = {
             vpcName: props.vpcName,
             accountId,

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

@@ -1,4 +1,5 @@
 import { type Environment, Stack, type StackProps } from "aws-cdk-lib";
+import { type CustomPermissionSets } from "../../config/aws/identityCenter.js";
 import { ScpPreset } from "../../config/aws/scpPreset.js";
 import type { ScpPresetProps } from "../../config/aws/scpPreset.js";
 import { OrganisationResource } from "../../resources/aws/organisation/index.js";
@@ -32,11 +33,14 @@ export declare class Organisation extends Stack {
     private accountRefs;
     private accountMap;
     private accountsConfig;
+    private identityCenter?;
     constructor(id: string, props: OrganisationProps);
     private createAccountReferences;
     private setupOrganisationFeatures;
     private setupCostAllocationTagActivator;
     private setupIdentityCenter;
+    declarePermissionSets(customs: CustomPermissionSets): void;
+    assignGroupMembers(members: Record<string, string[]>): void;
     getOrganisation(): OrganisationResource;
     getAccounts(): Record<string, string>;
     enableScps(props: ScpPresetProps): ScpPreset;

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

@@ -23,6 +23,7 @@ export class Organisation extends Stack {
     accountRefs = [];
     accountMap;
     accountsConfig;
+    identityCenter;
     constructor(id, props) {
         const config = getConfig();
         const env = props.env ?? {
@@ -42,8 +43,9 @@ export class Organisation extends Stack {
         }
         this.accountsConfig = props.accounts;
         const orgId = this.node.tryGetContext(CDK_CONTEXT_KEYS.ORG_ID);
-        const rootId = this.node.tryGetContext("rootId");
-        const managementAccountId = this.node.tryGetContext("managementAccountId") ?? this.account;
+        const rootId = this.node.tryGetContext(CDK_CONTEXT_KEYS.ROOT_ID);
+        const managementAccountId = this.node.tryGetContext(CDK_CONTEXT_KEYS.MANAGEMENT_ACCOUNT_ID) ??
+            this.account;
         if (!orgId || !rootId) {
             throw new Error("orgId and rootId must be provided via CDK context. Run deployment through the Fjall CLI.");
         }
@@ -76,7 +78,11 @@ export class Organisation extends Stack {
         this.setupCostAllocationTagActivator();
     }
     setupCostAllocationTagActivator() {
-        new CostAllocationTagActivator(this, "CostAllocationTagActivator");
+        const activator = new CostAllocationTagActivator(this, "CostAllocationTagActivator");
+        App.getInstance().addSchedule("CostAllocationTagActivatorSchedule", {
+            schedule: "rate(24 hours)",
+            target: activator
+        });
     }
     setupIdentityCenter(identityCenter, managementAccountId) {
         if (identityCenter) {
@@ -88,11 +94,23 @@ export class Organisation extends Stack {
                     ssoAccounts[name] = id;
                 }
             }
-            new IdentityCenter(this, "IdentityCenter", {
+            this.identityCenter = new IdentityCenter(this, "IdentityCenter", {
                 accounts: ssoAccounts
             });
         }
     }
+    declarePermissionSets(customs) {
+        if (this.identityCenter === undefined) {
+            throw new Error("Identity Center is not enabled. Pass identityCenter: true to OrganisationFactory.");
+        }
+        this.identityCenter.declarePermissionSets(customs);
+    }
+    assignGroupMembers(members) {
+        if (this.identityCenter === undefined) {
+            throw new Error("Identity Center is not enabled. Pass identityCenter: true to OrganisationFactory.");
+        }
+        this.identityCenter.assignGroupMembers(members);
+    }
     getOrganisation() {
         return this.org;
     }

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

@@ -1,9 +1,8 @@
 import { Construct } from "constructs";
 import { type IBucket, type EventType, type IBucketNotificationDestination, type NotificationKeyFilter } from "aws-cdk-lib/aws-s3";
-import { BucketDeployment } from "aws-cdk-lib/aws-s3-deployment";
 import { type IGrantable, type Grant } from "aws-cdk-lib/aws-iam";
 import type App from "../../app.js";
-import { type WebsiteHostingConfig } from "../../resources/aws/storage/index.js";
+import { BucketDeployment, type WebsiteHostingConfig } from "../../resources/aws/storage/index.js";
 import { type BackupTier } from "../../utils/backupTierMapping.js";
 import { type IStorage } from "./interfaces/storage.js";
 import { type IStorageConnector } from "./interfaces/connector.js";

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

@@ -1,9 +1,9 @@
 import { Construct } from "constructs";
 import { BucketEncryption, HttpMethods } from "aws-cdk-lib/aws-s3";
-import { BucketDeployment, Source, CacheControl } from "aws-cdk-lib/aws-s3-deployment";
+import { Source, CacheControl } from "aws-cdk-lib/aws-s3-deployment";
 import { Key } from "aws-cdk-lib/aws-kms";
 import { CfnOutput, Duration, RemovalPolicy, Stack } from "aws-cdk-lib";
-import { S3Bucket } from "../../resources/aws/storage/index.js";
+import { BucketDeployment, S3Bucket } from "../../resources/aws/storage/index.js";
 import { FjallLogger } from "../../utils/validationLogger.js";
 export { isStorage } from "./interfaces/storage.js";
 function toBucketEncryption(encryption) {
@@ -50,6 +50,7 @@ export class Storage extends Construct {
     bucketDeployment;
     constructor(scope, id, props) {
         super(scope, id);
+        validateStorageProps(props);
         const encryptionKey = props.kmsKeyArn
             ? Key.fromKeyArn(this, `${id}KmsKey`, props.kmsKeyArn)
             : undefined;

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

@@ -1,3 +1,4 @@
+import { Stack } from "aws-cdk-lib";
 import { StringListParameter, StringParameter } from "aws-cdk-lib/aws-ssm";
 import { buildSsmPrefix, DEFAULT_ORG_ID, resolveOrgId } from "../../utils/cdkContext.js";
 import { VpcPeeringConnection } from "../../resources/aws/networking/vpcPeeringConnection.js";
@@ -16,13 +17,14 @@ export class VpcPeerFactory {
             const peerRouteTableIds = props.peerRouteTableIds ??
                 StringListParameter.valueForTypedListParameter(scope, `${ssmPrefix}/route-table-ids`);
             const resolvedPeerOrgId = orgId !== DEFAULT_ORG_ID ? orgId : undefined;
+            const peerRegion = props.peerRegion ?? Stack.of(scope).region;
             return new VpcPeeringConnection(scope, id, {
                 localVpc,
                 localVpcCidr: localVpc.vpcCidrBlock,
                 peerVpcId,
                 peerVpcCidr,
                 peerAccountId: props.peerAccountId,
-                peerRegion: props.peerRegion,
+                peerRegion,
                 peerRoleArn,
                 peerRouteTableIds,
                 enableDnsResolution: props.enableDnsResolution,

package/dist/lib/resources/aws/analytics/clickhouse.js

@@ -5,7 +5,7 @@ import { InstanceType, SubnetType, Connections, Port, UserData } from "aws-cdk-l
 import { AutoScalingGroup, Monitoring, BlockDeviceVolume, EbsDeviceVolumeType } from "aws-cdk-lib/aws-autoscaling";
 import { Duration, Stack } from "aws-cdk-lib";
 import { Construct } from "constructs";
-import { RetentionDays } from "aws-cdk-lib/aws-logs";
+import { LogGroup, RetentionDays } from "aws-cdk-lib/aws-logs";
 import { S3Bucket } from "../storage/s3.js";
 import { Secret } from "../secrets/secret.js";
 import { vpcHasNatGateways } from "../../../utils/vpcUtils.js";
@@ -238,7 +238,10 @@ export default class ClickHouse extends Construct {
         });
         // 11. Scheduled weekly backup to S3
         const backupDestUrl = `https://${backupBucket.bucketName}.s3.${Stack.of(this).region}.amazonaws.com/`;
-        const backupTask = new ScheduledEc2Task(this, "ClickHouseBackupTask", {
+        const backupTaskLogGroup = new LogGroup(this, "ClickHouseBackupTaskLogGroup", {
+            retention: RetentionDays.TWO_WEEKS
+        });
+        new ScheduledEc2Task(this, "ClickHouseBackupTask", {
             cluster,
             schedule: Schedule.expression(BACKUP_SCHEDULE),
             scheduledEc2TaskImageOptions: {
@@ -255,7 +258,7 @@ export default class ClickHouse extends Construct {
                 },
                 logDriver: LogDriver.awsLogs({
                     streamPrefix: "clickhouse-backup",
-                    logRetention: RetentionDays.TWO_WEEKS
+                    logGroup: backupTaskLogGroup
                 })
             },
             securityGroups: [securityGroup],
@@ -263,9 +266,11 @@ export default class ClickHouse extends Construct {
                 subnetType
             }
         });
-        // 12. Grant S3 write access to the backup task role
-        backupBucket.grantReadWrite(backupTask.taskDefinition.taskRole);
-        // 13. Grant secret read to execution role
+        // BACKUP DATABASE TO S3 runs inside the ClickHouse server process on the
+        // ASG instance, not the ephemeral backup task; the grant must therefore
+        // attach to the ASG instance role, not the task role.
+        backupBucket.grantReadWrite(asg.role);
+        // 12. Grant secret read to execution role
         const executionRole = taskDefinition.executionRole;
         if (!executionRole) {
             throw new Error("ClickHouse task definition has no execution role — cannot grant secret access");
@@ -274,15 +279,19 @@ export default class ClickHouse extends Construct {
         auditPasswordSecret.secret.grantRead(executionRole);
         backupPasswordSecret.secret.grantRead(executionRole);
         schemaPasswordSecret.secret.grantRead(executionRole);
-        // 14. CloudWatch alarms (CPU, memory, disk) — wired only when an SNS topic is supplied
         if (props.alarmTopic) {
+            if (!props.webappLogGroup) {
+                throw new Error("ClickHouse: alarmTopic requires webappLogGroup so the stuck-merge metric filter can be wired.");
+            }
             createClickHouseAlarms({
                 scope: this,
                 asg,
-                alarmTopic: props.alarmTopic
+                alarmTopic: props.alarmTopic,
+                webappLogGroup: props.webappLogGroup,
+                backupTaskLogGroup
             });
         }
-        // 15. Connections and outputs
+        // 13. Connections and outputs
         this.connections = new Connections({
             securityGroups: [securityGroup],
             defaultPort: Port.tcp(CLICKHOUSE_HTTP_PORT)

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

@@ -1,6 +1,7 @@
 import { Alarm } from "aws-cdk-lib/aws-cloudwatch";
 import type { AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
 import type { ITopic } from "aws-cdk-lib/aws-sns";
+import type { ILogGroup } from "aws-cdk-lib/aws-logs";
 import type { Construct } from "constructs";
 export interface ClickHouseAlarmThresholds {
     /** EC2 host CPU % over 5 min. Default 90. */
@@ -16,19 +17,33 @@ export interface ClickHouseAlarmsProps {
     scope: Construct;
     asg: AutoScalingGroup;
     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 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).
+     */
+    backupTaskLogGroup: ILogGroup;
     config?: ClickHouseAlarmThresholds;
 }
 /**
  * Single-node ClickHouse posture alarms. Covers host-level CPU + (optional)
- * memory and disk via the CloudWatch Agent metric namespace `CWAgent`.
+ * memory and disk via the CloudWatch Agent metric namespace `CWAgent`, plus
+ * two log-driven alarms:
  *
- * Engine-level alarms (parts count, failed inserts) require the Prometheus
- * exporter to be scraped into CW custom metrics. The Prometheus endpoint is
- * enabled in the user-data XML (port 9363); the scraper is a follow-up.
- *
- * Stuck merges are detected app-side: `client.ts` queries `system.merges`
- * every 5 min and logs `serverLogger.warn("ClickHouse", "Stuck merge detected")`
- * when elapsed > 30 min. A CW Logs metric filter on that pattern + alarm
- * completes the circuit once the webapp log group ARN is available here.
+ * - **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`).
  */
 export declare function createClickHouseAlarms(props: ClickHouseAlarmsProps): Alarm[];

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

@@ -2,22 +2,25 @@ import { Duration } from "aws-cdk-lib";
 import { Alarm, ComparisonOperator, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
 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 "../monitoring/alarmDefaults.js";
+const CLICKHOUSE_METRIC_NAMESPACE = "Fjall/ClickHouse";
 /**
  * Single-node ClickHouse posture alarms. Covers host-level CPU + (optional)
- * memory and disk via the CloudWatch Agent metric namespace `CWAgent`.
+ * memory and disk via the CloudWatch Agent metric namespace `CWAgent`, plus
+ * two log-driven alarms:
  *
- * Engine-level alarms (parts count, failed inserts) require the Prometheus
- * exporter to be scraped into CW custom metrics. The Prometheus endpoint is
- * enabled in the user-data XML (port 9363); the scraper is a follow-up.
- *
- * Stuck merges are detected app-side: `client.ts` queries `system.merges`
- * every 5 min and logs `serverLogger.warn("ClickHouse", "Stuck merge detected")`
- * when elapsed > 30 min. A CW Logs metric filter on that pattern + alarm
- * completes the circuit once the webapp log group ARN is available here.
+ * - **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`).
  */
 export function createClickHouseAlarms(props) {
-    const { scope, asg, alarmTopic, config = {} } = props;
+    const { scope, asg, alarmTopic, webappLogGroup, backupTaskLogGroup, config = {} } = props;
     const alarms = [];
     const snsAction = new SnsAction(alarmTopic);
     const asgName = asg.autoScalingGroupName;
@@ -85,5 +88,53 @@ 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 ASG instance role grant on backup bucket", undefined),
+        metric: new Metric({
+            namespace: CLICKHOUSE_METRIC_NAMESPACE,
+            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/analytics/clickhouseConstants.d.ts

@@ -64,10 +64,10 @@ export declare const OPTIMISE_MV_TABLES: readonly ["metrics_hourly_mv", "metrics
 /** Resource allocation for the lightweight optimise task. */
 export declare const OPTIMISE_TASK_MEMORY_MIB = 256;
 export declare const OPTIMISE_TASK_CPU_UNITS = 256;
-/** Automated backup schedule (weekly, Sunday 03:00 UTC — low-traffic window). */
-export declare const BACKUP_SCHEDULE = "cron(0 3 ? * SUN *)";
+/** Automated backup schedule (daily 03:00 UTC — low-traffic window). */
+export declare const BACKUP_SCHEDULE = "cron(0 3 * * ? *)";
 /** Resource allocation for the backup task (lightweight — clickhouse-client only). */
 export declare const BACKUP_TASK_MEMORY_MIB = 256;
 export declare const BACKUP_TASK_CPU_UNITS = 256;
-/** Backup object expiration: 14 days (retains 2 weekly snapshots). */
+/** Backup object expiration: 14 days (retains 14 daily snapshots). */
 export declare const BACKUP_RETENTION_DAYS = 14;

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

@@ -80,10 +80,10 @@ export const OPTIMISE_MV_TABLES = [
 /** Resource allocation for the lightweight optimise task. */
 export const OPTIMISE_TASK_MEMORY_MIB = 256;
 export const OPTIMISE_TASK_CPU_UNITS = 256;
-/** Automated backup schedule (weekly, Sunday 03:00 UTC — low-traffic window). */
-export const BACKUP_SCHEDULE = "cron(0 3 ? * SUN *)";
+/** Automated backup schedule (daily 03:00 UTC — low-traffic window). */
+export const BACKUP_SCHEDULE = "cron(0 3 * * ? *)";
 /** Resource allocation for the backup task (lightweight — clickhouse-client only). */
 export const BACKUP_TASK_MEMORY_MIB = 256;
 export const BACKUP_TASK_CPU_UNITS = 256;
-/** Backup object expiration: 14 days (retains 2 weekly snapshots). */
+/** Backup object expiration: 14 days (retains 14 daily snapshots). */
 export const BACKUP_RETENTION_DAYS = 14;

package/dist/lib/resources/aws/analytics/clickhouseTypes.d.ts

@@ -1,4 +1,5 @@
 import type { IVpc, ISecurityGroup } from "aws-cdk-lib/aws-ec2";
+import type { ILogGroup } from "aws-cdk-lib/aws-logs";
 import type { IBucket } from "aws-cdk-lib/aws-s3";
 import type { ISecret } from "aws-cdk-lib/aws-secretsmanager";
 import type { ITopic } from "aws-cdk-lib/aws-sns";
@@ -23,10 +24,15 @@ export interface ClickHouseProps {
      */
     r2Config?: ClickHouseR2Config;
     /**
-     * SNS topic for CloudWatch alarms (CPU, memory, disk).
+     * SNS topic for CloudWatch alarms (CPU, memory, disk, stuck merges).
      * If omitted, posture alarms are not created.
      */
     alarmTopic?: ITopic;
+    /**
+     * Webapp log group, required when `alarmTopic` is set so the stuck-merge
+     * metric filter can read the structured warning emitted by `client.ts`.
+     */
+    webappLogGroup?: ILogGroup;
 }
 /** Cloudflare R2 configuration for tiered storage and backups. */
 export interface ClickHouseR2Config {