@fjall/components-infrastructure 0.96.0 → 0.99.1

package/dist/lib/resources/aws/messaging/eventbridge.js

@@ -1,25 +1,37 @@
 import { Construct } from "constructs";
 import { CfnOutput } from "aws-cdk-lib";
 import { EventBus } from "aws-cdk-lib/aws-events";
+import { env } from "../../../utils/env.js";
 import { toRemovalPolicy } from "./utils.js";
 export class EventBridgeBus extends Construct {
     id;
-    eventBus;
+    #eventBus;
     constructor(scope, id, props) {
         super(scope, id);
         this.id = id;
-        this.eventBus = new EventBus(this, `${id}EventBus`, {
-            eventBusName: props.eventBusName
+        if (props.importedBus !== undefined) {
+            this.#eventBus = props.importedBus;
+            return;
+        }
+        const description = props.description ??
+            (props.appName
+                ? `EventBus ${props.appName} — Fjall app event bus`
+                : undefined);
+        const removalPolicyValue = props.removalPolicy ?? env({ default: "DESTROY", production: "RETAIN" });
+        const ownedBus = new EventBus(this, `${id}EventBus`, {
+            eventBusName: props.eventBusName,
+            description
         });
-        this.eventBus.applyRemovalPolicy(toRemovalPolicy(props.removalPolicy));
+        this.#eventBus = ownedBus;
+        ownedBus.applyRemovalPolicy(toRemovalPolicy(removalPolicyValue));
         new CfnOutput(this, `${id}EventBusArn`, {
             key: `${id}EventBusArn`,
-            value: this.eventBus.eventBusArn,
+            value: ownedBus.eventBusArn,
             description: `EventBridge event bus ARN for ${id}`
         });
         new CfnOutput(this, `${id}EventBusName`, {
             key: `${id}EventBusName`,
-            value: this.eventBus.eventBusName,
+            value: ownedBus.eventBusName,
             description: `EventBridge event bus name for ${id}`
         });
     }
@@ -27,24 +39,24 @@ export class EventBridgeBus extends Construct {
      * Get the event bus ARN.
      */
     getEventBusArn() {
-        return this.eventBus.eventBusArn;
+        return this.#eventBus.eventBusArn;
     }
     /**
      * Get the event bus name.
      */
     getEventBusName() {
-        return this.eventBus.eventBusName;
+        return this.#eventBus.eventBusName;
     }
     /**
      * Get the underlying CDK EventBus construct.
      */
     getEventBus() {
-        return this.eventBus;
+        return this.#eventBus;
     }
     /**
      * Grant put events permissions to the grantee.
      */
     grantPutEventsTo(grantee) {
-        return this.eventBus.grantPutEventsTo(grantee);
+        return this.#eventBus.grantPutEventsTo(grantee);
     }
 }

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

@@ -2,3 +2,8 @@ export * from "./eventbridge.js";
 export * from "./sns.js";
 export * from "./sqs.js";
 export * from "./utils.js";
+export { Schedule, type ScheduleProps, type ScheduleTarget } from "./schedule.js";
+export { Subscription, type SubscriptionProps, type SubscriptionTarget } from "./subscription.js";
+export type { EventBridgeRetryPolicy } from "./eventBridgeRule.js";
+export type { EcsScheduleTarget } from "./eventTargets.js";
+export type { ScheduleAlarmThresholds } from "./schedule.js";

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

@@ -2,3 +2,5 @@ export * from "./eventbridge.js";
 export * from "./sns.js";
 export * from "./sqs.js";
 export * from "./utils.js";
+export { Schedule } from "./schedule.js";
+export { Subscription } from "./subscription.js";

package/dist/lib/resources/aws/messaging/schedule.d.ts

@@ -0,0 +1,118 @@
+import { Construct } from "constructs";
+import { type IRule } from "aws-cdk-lib/aws-events";
+import type { IRole } from "aws-cdk-lib/aws-iam";
+import type { ITopic } from "aws-cdk-lib/aws-sns";
+import { type EventBridgeRetryPolicy } from "./eventBridgeRule.js";
+import type { ScheduleTargetInput } from "./eventTargets.js";
+import type { SQSQueue } from "./sqs.js";
+import type { ScheduleAlarmThresholds } from "../monitoring/scheduleAlarms.js";
+export type { ScheduleAlarmThresholds } from "../monitoring/scheduleAlarms.js";
+/**
+ * Public input type for `Schedule.target`. Re-exported so consumers can
+ * type variables against it. Callers pass wrapper instances directly (D2).
+ */
+export type ScheduleTarget = ScheduleTargetInput;
+/**
+ * Construction-time props for `Schedule`. Owns the user-facing surface;
+ * description / DLQ / KMS-grant / retry-policy / alarm wiring all flow
+ * through the `EventBridgeRule` base wrapper.
+ */
+export interface ScheduleProps {
+    /** Cron or rate expression. Validated against `VALIDATION_PATTERNS.SCHEDULE_EXPRESSION`. */
+    schedule: string;
+    /** What receives the event (Fjall wrapper instance per D2). */
+    target: ScheduleTarget;
+    /**
+     * SQS FIFO message group id. Required when target is a FIFO queue (D14);
+     * rejected for non-queue targets and non-FIFO queues. Validation lives in
+     * `resolveTarget(...)` (single source of truth).
+     */
+    messageGroupId?: string;
+    /**
+     * JSON payload sent to the target on every tick (D5 — typed as
+     * `Record<string, unknown>`). Translates to `message` (SQS) or `event`
+     * (Lambda / EventBus) on the underlying adapter. Values may be
+     * `EventField.*` tokens for payload-template substitution.
+     * `scheduledAt: EventField.time` is auto-injected unless the caller
+     * already provides a `scheduledAt` key.
+     *
+     * Not supported on ECS targets — CDK's `EcsTask` adapter ignores arbitrary
+     * input; use container command/environment overrides on the task definition
+     * instead. Passing `payload` against an ECS target throws.
+     *
+     * @example
+     * app.addSchedule("MetricsCollection", {
+     *   schedule: "rate(5 minutes)",
+     *   target: monitoringQueue,
+     *   payload: { type: "metrics-collection" },
+     *   messageGroupId: "monitoring-metrics-collection"
+     * });
+     */
+    payload?: Record<string, unknown>;
+    /**
+     * Application name used to build the default description when `description`
+     * is not supplied. Constructor-injected by `App.addSchedule(...)` per
+     * Stage-2 v2 — NOT derived from `Stack.of(this).stackName`.
+     */
+    appName?: string;
+    /** Override the default description ("Schedule <id> for <appName> — fires <schedule>"). */
+    description?: string;
+    /**
+     * When `{ enabled: true }` provisions a sibling `<id>Dlq`; otherwise honour
+     * the supplied queue. Typed against the resource-layer `SQSQueue` so the
+     * patterns-layer `QueueMessaging` (which extends `SQSQueue`) is still
+     * accepted without crossing the layer boundary.
+     */
+    deadLetterQueue?: {
+        enabled: true;
+        queue?: SQSQueue;
+    } | {
+        enabled: false;
+    } | SQSQueue;
+    /**
+     * Retry policy. Default for Schedule is `Duration.minutes(15)` / `2 attempts`
+     * per D15. AWS default of 24h/185 is wrong for cron-driven targets — overlapping
+     * retries block next ticks.
+     */
+    retryPolicy?: EventBridgeRetryPolicy;
+    enabled?: boolean;
+    role?: IRole;
+    crossStackScope?: Construct;
+    /** SNS topic for D13 alarms. When supplied, alarms are auto-provisioned unless `alarms === false`. */
+    alertsTopic?: ITopic;
+    /** Suppress alarms even when `alertsTopic` is supplied. */
+    alarms?: boolean;
+    /** Tunable alarm thresholds; ignored when `alertsTopic` is undefined OR `alarms === false`. */
+    alarmConfig?: ScheduleAlarmThresholds;
+    /** Application id tag for alarm webhook routing. */
+    applicationId?: string;
+    /**
+     * Stack placement override for `App.addSchedule(...)`. Defaults to the
+     * messaging stack; set to `"compute"` when the schedule's target lives in
+     * the compute stack and CFN cross-stack output churn is undesired.
+     */
+    stackPlacement?: "messaging" | "compute";
+}
+/**
+ * Schedule resource — composes an EventBridge `Rule` with a schedule expression
+ * and a single target. Description, DLQ, KMS-grant on CMK-encrypted DLQs,
+ * retry-policy default, FIFO validation, and D13 alarm wiring all delegate to
+ * the shared `EventBridgeRule` base wrapper. Tags propagate from the App
+ * aspect — no per-wrapper `applyCostAllocationTags` call per D10.
+ *
+ * **Idempotency contract:** EventBridge can deliver the same payload up to
+ * `retryAttempts + 1` times during transient target failures. SQS-targeted
+ * schedules with FIFO + content-based deduplication absorb same-content retries
+ * automatically; Lambda-targeted handlers MUST be idempotent (write-once,
+ * conditional updates, idempotency keys).
+ */
+export declare class Schedule extends Construct {
+    #private;
+    readonly id: string;
+    readonly deadLetterQueue?: SQSQueue;
+    constructor(scope: Construct, id: string, props: ScheduleProps);
+    /** Get the underlying EventBridge rule (interface-typed per D18(a)). */
+    getRule(): IRule;
+    /** Get the ARN of the underlying rule. */
+    getRuleArn(): string;
+}

package/dist/lib/resources/aws/messaging/schedule.js

@@ -0,0 +1,64 @@
+import { Construct } from "constructs";
+import { Schedule as CdkSchedule } from "aws-cdk-lib/aws-events";
+import { VALIDATION_PATTERNS, VALIDATION_MESSAGES, parseRateExpression } from "@fjall/generator";
+import { EventBridgeRule, buildScheduleDescription } from "./eventBridgeRule.js";
+/**
+ * Schedule resource — composes an EventBridge `Rule` with a schedule expression
+ * and a single target. Description, DLQ, KMS-grant on CMK-encrypted DLQs,
+ * retry-policy default, FIFO validation, and D13 alarm wiring all delegate to
+ * the shared `EventBridgeRule` base wrapper. Tags propagate from the App
+ * aspect — no per-wrapper `applyCostAllocationTags` call per D10.
+ *
+ * **Idempotency contract:** EventBridge can deliver the same payload up to
+ * `retryAttempts + 1` times during transient target failures. SQS-targeted
+ * schedules with FIFO + content-based deduplication absorb same-content retries
+ * automatically; Lambda-targeted handlers MUST be idempotent (write-once,
+ * conditional updates, idempotency keys).
+ */
+export class Schedule extends Construct {
+    id;
+    deadLetterQueue;
+    #base;
+    constructor(scope, id, props) {
+        super(scope, id);
+        this.id = id;
+        if (!VALIDATION_PATTERNS.SCHEDULE_EXPRESSION.test(props.schedule)) {
+            throw new Error(`${VALIDATION_MESSAGES.SCHEDULE_EXPRESSION} (received: ${props.schedule})`);
+        }
+        const description = props.description ??
+            (props.appName
+                ? buildScheduleDescription(props.appName, id, props.schedule)
+                : undefined);
+        const cadence = parseRateExpression(props.schedule);
+        const expectedTicksPerHour = cadence !== undefined ? (60 * 60_000) / cadence.everyMs : undefined;
+        this.#base = new EventBridgeRule(this, `${id}Base`, {
+            kind: "schedule",
+            schedule: CdkSchedule.expression(props.schedule),
+            description,
+            target: props.target,
+            messageGroupId: props.messageGroupId,
+            payload: props.payload,
+            deadLetterQueue: props.deadLetterQueue,
+            retryPolicy: props.retryPolicy,
+            enabled: props.enabled,
+            role: props.role,
+            crossStackScope: props.crossStackScope,
+            alertsTopic: props.alertsTopic,
+            alarms: props.alarms,
+            alarmConfig: props.alarmConfig,
+            applicationId: props.applicationId,
+            expectedTicksPerHour
+        });
+        if (this.#base.deadLetterQueue !== undefined) {
+            this.deadLetterQueue = this.#base.deadLetterQueue;
+        }
+    }
+    /** Get the underlying EventBridge rule (interface-typed per D18(a)). */
+    getRule() {
+        return this.#base.getRule();
+    }
+    /** Get the ARN of the underlying rule. */
+    getRuleArn() {
+        return this.#base.getRuleArn();
+    }
+}

package/dist/lib/resources/aws/messaging/sns.d.ts

@@ -1,12 +1,13 @@
 import { Construct } from "constructs";
 import { type ITopic } from "aws-cdk-lib/aws-sns";
 import { type IGrantable, type Grant } from "aws-cdk-lib/aws-iam";
+import { type RemovalPolicyString } from "./utils.js";
 export interface SNSTopicProps {
     topicName?: string;
     displayName?: string;
     fifo?: boolean;
     contentBasedDeduplication?: boolean;
-    removalPolicy?: "DESTROY" | "RETAIN";
+    removalPolicy?: RemovalPolicyString;
 }
 export declare class SNSTopic extends Construct {
     readonly id: string;

package/dist/lib/resources/aws/messaging/sqs.d.ts

@@ -1,6 +1,7 @@
 import { Construct } from "constructs";
 import { type IQueue } from "aws-cdk-lib/aws-sqs";
 import { type IGrantable, type Grant } from "aws-cdk-lib/aws-iam";
+import { type RemovalPolicyString } from "./utils.js";
 /**
  * AWS SQS service limits and defaults.
  * @see https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-quotas.html
@@ -59,7 +60,7 @@ export interface SQSQueueProps {
     contentBasedDeduplication?: boolean;
     fifoThroughputLimit?: "perQueue" | "perMessageGroupId";
     deduplicationScope?: "queue" | "messageGroup";
-    removalPolicy?: "DESTROY" | "RETAIN";
+    removalPolicy?: RemovalPolicyString;
 }
 export declare class SQSQueue extends Construct {
     readonly id: string;

package/dist/lib/resources/aws/messaging/subscription.d.ts

@@ -0,0 +1,112 @@
+import { Construct } from "constructs";
+import { type EventPattern, type IEventBus, type IRule } from "aws-cdk-lib/aws-events";
+import type { IRole } from "aws-cdk-lib/aws-iam";
+import type { ITopic } from "aws-cdk-lib/aws-sns";
+import { type EventBridgeRetryPolicy } from "./eventBridgeRule.js";
+import type { ScheduleAlarmThresholds } from "../monitoring/scheduleAlarms.js";
+import type { SubscriptionTargetInput } from "./eventTargets.js";
+import type { SQSQueue } from "./sqs.js";
+/**
+ * Public input type for `Subscription.target`. Re-exported so consumers can
+ * type variables against it. Callers pass wrapper instances directly (D2).
+ */
+export type SubscriptionTarget = SubscriptionTargetInput;
+/**
+ * Construction-time props for `Subscription`. Owns the user-facing surface;
+ * description / DLQ / KMS-grant / retry-policy / alarm wiring all flow
+ * through the `EventBridgeRule` base wrapper.
+ */
+export interface SubscriptionProps {
+    /** EventBridge event-pattern object — re-exported from `aws-cdk-lib/aws-events`. */
+    pattern: EventPattern;
+    /** What receives matching events (Fjall wrapper instance per D2). */
+    target: SubscriptionTarget;
+    /**
+     * SQS FIFO message group id. Required when target is a FIFO queue (D14);
+     * rejected for non-queue targets and non-FIFO queues. Validation lives in
+     * `resolveTarget(...)` (single source of truth).
+     */
+    messageGroupId?: string;
+    /**
+     * Optional JSON payload that overrides the matched event detail before
+     * delivery to the target (D5 — typed as `Record<string, unknown>`).
+     * Translates to `message` (SQS) or `event` (Lambda / EventBus / CodeBuild)
+     * on the underlying adapter. Values may be `EventField.*` tokens for
+     * payload-template substitution (e.g.
+     * `EventField.fromPath("$.detail.repository.name")`). When omitted, the
+     * full matched event is forwarded verbatim — the common pub/sub case.
+     *
+     * Not supported on ECS targets — CDK's `EcsTask` adapter ignores arbitrary
+     * input; use container command/environment overrides on the task definition
+     * instead. Passing `payload` against an ECS target throws.
+     */
+    payload?: Record<string, unknown>;
+    /**
+     * Application name used to build the default description when `description`
+     * is not supplied. Constructor-injected by `EventBusMessaging.subscribe(...)`.
+     */
+    appName?: string;
+    /** Override the default description ("Subscription <id> for <appName>"). */
+    description?: string;
+    /** Bus that owns this subscription. Threaded by `EventBusMessaging.subscribe(...)`. */
+    eventBus?: IEventBus;
+    /**
+     * When `{ enabled: true }` provisions a sibling `<id>Dlq`; otherwise honour
+     * the supplied queue. Typed against the resource-layer `SQSQueue` so the
+     * patterns-layer `QueueMessaging` (which extends `SQSQueue`) is still
+     * accepted without crossing the layer boundary.
+     */
+    deadLetterQueue?: {
+        enabled: true;
+        queue?: SQSQueue;
+    } | {
+        enabled: false;
+    } | SQSQueue;
+    /**
+     * Retry policy. Subscription default is AWS defaults (24h / 185 attempts) per
+     * D15 — pub/sub is business-signal, late > never. Override to tighter windows
+     * for time-sensitive subscriptions.
+     */
+    retryPolicy?: EventBridgeRetryPolicy;
+    enabled?: boolean;
+    role?: IRole;
+    crossStackScope?: Construct;
+    /** SNS topic for D13 alarms. When supplied, alarms are auto-provisioned unless `alarms === false`. */
+    alertsTopic?: ITopic;
+    /** Suppress alarms even when `alertsTopic` is supplied. */
+    alarms?: boolean;
+    /** Tunable alarm thresholds; ignored when `alertsTopic` is undefined OR `alarms === false`. */
+    alarmConfig?: ScheduleAlarmThresholds;
+    /** Application id tag for alarm webhook routing. */
+    applicationId?: string;
+}
+/**
+ * Subscription resource — composes an EventBridge `Rule` with an event-pattern
+ * filter and a single target. Shares the `EventBridgeRule` base wrapper with
+ * `Schedule`; the only behavioural difference is `kind: "subscription"`,
+ * which leaves retry policy unset (AWS defaults per D15) and suppresses the
+ * D13 missed-tick `MatchedEvents` alarm (subscriptions are event-driven, not
+ * periodic, so the missed-tick semantics don't apply).
+ *
+ * **Idempotency contract:** EventBridge can deliver the same payload up to
+ * `retryAttempts + 1` times. SQS-targeted subscriptions with FIFO + content-based
+ * deduplication absorb same-content retries; Lambda handlers MUST be idempotent.
+ *
+ * **Delete ordering (D17):** when the bus's removalPolicy is DESTROY, the
+ * subscription's underlying rule must delete BEFORE the bus to avoid CFN's
+ * `EventBus can't be deleted since it has rules` error. The constructor calls
+ * `rule.node.addDependency(eventBus)` (rule depends on bus) so CFN creates
+ * the bus first and tears the rule down first. The dependency is added
+ * unconditionally because `IEventBus` does not expose `removalPolicy`; for
+ * RETAIN buses the dep is harmless.
+ */
+export declare class Subscription extends Construct {
+    #private;
+    readonly id: string;
+    readonly deadLetterQueue?: SQSQueue;
+    constructor(scope: Construct, id: string, props: SubscriptionProps);
+    /** Get the underlying EventBridge rule (interface-typed per D18(a)). */
+    getRule(): IRule;
+    /** Get the ARN of the underlying rule. */
+    getRuleArn(): string;
+}

package/dist/lib/resources/aws/messaging/subscription.js

@@ -0,0 +1,67 @@
+import { Construct } from "constructs";
+import { EventBridgeRule, buildSubscriptionDescription } from "./eventBridgeRule.js";
+/**
+ * Subscription resource — composes an EventBridge `Rule` with an event-pattern
+ * filter and a single target. Shares the `EventBridgeRule` base wrapper with
+ * `Schedule`; the only behavioural difference is `kind: "subscription"`,
+ * which leaves retry policy unset (AWS defaults per D15) and suppresses the
+ * D13 missed-tick `MatchedEvents` alarm (subscriptions are event-driven, not
+ * periodic, so the missed-tick semantics don't apply).
+ *
+ * **Idempotency contract:** EventBridge can deliver the same payload up to
+ * `retryAttempts + 1` times. SQS-targeted subscriptions with FIFO + content-based
+ * deduplication absorb same-content retries; Lambda handlers MUST be idempotent.
+ *
+ * **Delete ordering (D17):** when the bus's removalPolicy is DESTROY, the
+ * subscription's underlying rule must delete BEFORE the bus to avoid CFN's
+ * `EventBus can't be deleted since it has rules` error. The constructor calls
+ * `rule.node.addDependency(eventBus)` (rule depends on bus) so CFN creates
+ * the bus first and tears the rule down first. The dependency is added
+ * unconditionally because `IEventBus` does not expose `removalPolicy`; for
+ * RETAIN buses the dep is harmless.
+ */
+export class Subscription extends Construct {
+    id;
+    deadLetterQueue;
+    #base;
+    constructor(scope, id, props) {
+        super(scope, id);
+        this.id = id;
+        const description = props.description ??
+            (props.appName
+                ? buildSubscriptionDescription(props.appName, id)
+                : undefined);
+        this.#base = new EventBridgeRule(this, `${id}Base`, {
+            kind: "subscription",
+            eventPattern: props.pattern,
+            description,
+            target: props.target,
+            messageGroupId: props.messageGroupId,
+            payload: props.payload,
+            eventBus: props.eventBus,
+            deadLetterQueue: props.deadLetterQueue,
+            retryPolicy: props.retryPolicy,
+            enabled: props.enabled,
+            role: props.role,
+            crossStackScope: props.crossStackScope,
+            alertsTopic: props.alertsTopic,
+            alarms: props.alarms,
+            alarmConfig: props.alarmConfig,
+            applicationId: props.applicationId
+        });
+        if (this.#base.deadLetterQueue !== undefined) {
+            this.deadLetterQueue = this.#base.deadLetterQueue;
+        }
+        if (props.eventBus !== undefined) {
+            this.#base.getRule().node.addDependency(props.eventBus);
+        }
+    }
+    /** Get the underlying EventBridge rule (interface-typed per D18(a)). */
+    getRule() {
+        return this.#base.getRule();
+    }
+    /** Get the ARN of the underlying rule. */
+    getRuleArn() {
+        return this.#base.getRuleArn();
+    }
+}

package/dist/lib/resources/aws/messaging/utils.d.ts

@@ -1,2 +1,8 @@
+import { Schedule as CdkSchedule, type CronOptions } from "aws-cdk-lib/aws-events";
+import { type Duration } from "aws-cdk-lib";
 export { toRemovalPolicy } from "../../../utils/removalPolicy.js";
 export type RemovalPolicyString = "DESTROY" | "RETAIN";
+export type ScheduleExpression = CdkSchedule;
+export declare function cronSchedule(options: CronOptions): CdkSchedule;
+export declare function rateSchedule(duration: Duration): CdkSchedule;
+export declare function expressionSchedule(expression: string): CdkSchedule;

package/dist/lib/resources/aws/messaging/utils.js

@@ -1 +1,11 @@
+import { Schedule as CdkSchedule } from "aws-cdk-lib/aws-events";
 export { toRemovalPolicy } from "../../../utils/removalPolicy.js";
+export function cronSchedule(options) {
+    return CdkSchedule.cron(options);
+}
+export function rateSchedule(duration) {
+    return CdkSchedule.rate(duration);
+}
+export function expressionSchedule(expression) {
+    return CdkSchedule.expression(expression);
+}

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

@@ -0,0 +1,60 @@
+import { Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { IRole } from "aws-cdk-lib/aws-iam";
+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. */
+    cpuThreshold?: number;
+    /** EC2 host memory % over 5 min (requires CWAgent). Default 80. */
+    memoryThreshold?: number;
+    /** EBS root-volume disk % used. Default 70 (warn) — paired with critical at 85. */
+    diskWarnThreshold?: number;
+    /** EBS root-volume disk % used. Default 85. */
+    diskCriticalThreshold?: number;
+}
+export interface ClickHouseAlarmsProps {
+    scope: Construct;
+    /**
+     * EC2 instance role (D10 — single accessor on `EcsCompute`). Drives the
+     * BACKUP failure alarm description so the responder grep target points at
+     * the role to inspect for missing S3 grants.
+     */
+    instanceRole: IRole;
+    /**
+     * AutoScalingGroupName token from `EcsCompute.getAutoScalingGroupName()`.
+     * Required for `AWS/EC2` and `CWAgent` metric dimensions (CloudWatch keys
+     * EC2 host metrics by ASG name; the role itself does not surface here).
+     */
+    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 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`, plus
+ * two log-driven alarms:
+ *
+ * - **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[];