@fjall/components-infrastructure 2.16.0 → 2.18.0

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/compute/persistentDataVolume.js

@@ -105,7 +105,11 @@ export class PersistentDataVolume extends Construct {
         Tags.of(this.volume).add(PERSISTENT_DATA_VOLUME_TAG_STACK_ID, Aws.STACK_ID);
         this.queue = new SQSQueue(this, `${id}Queue`, {
             visibilityTimeout: QUEUE_VISIBILITY_TIMEOUT_SECONDS,
-            deadLetterQueue: { enabled: true, maxReceiveCount: 5 }
+            deadLetterQueue: { enabled: true, maxReceiveCount: 5 },
+            // Transient volume-attach signals — no durable state (the EBS volume
+            // itself is SNAPSHOT above). Pinned DESTROY (now also the SQSQueue wrapper
+            // default) so a replacing deploy reclaims this queue + DLQ, not orphans.
+            removalPolicy: "DESTROY"
         });
         const sourcePath = path.resolve(__dirname, LAUNCHING_LAMBDA_SOURCE_FILE);
         const source = readFileSync(sourcePath, "utf-8");

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/messaging/sns.d.ts

@@ -7,6 +7,11 @@ export interface SNSTopicProps {
     displayName?: string;
     fifo?: boolean;
     contentBasedDeduplication?: boolean;
+    /**
+     * Removal policy for the topic. Defaults to DESTROY — a topic is a transient
+     * fan-out medium with no durable state (see the constructor). Pass "RETAIN"
+     * only for a topic that must survive stack deletion.
+     */
     removalPolicy?: RemovalPolicyString;
 }
 export declare class SNSTopic extends Construct {

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

@@ -22,7 +22,13 @@ export class SNSTopic extends Construct {
                 ? (props.contentBasedDeduplication ?? true)
                 : undefined
         });
-        this.topic.applyRemovalPolicy(toRemovalPolicy(props.removalPolicy));
+        // An SNS topic is a transient fan-out medium: it holds no durable state
+        // (subscriptions are re-created by the next deploy), so the wrapper defaults
+        // to DESTROY — deliberately NOT the env-aware production->RETAIN of
+        // data-bearing wrappers (S3, EventBus). RETAIN here buys no protection and
+        // orphans the topic on a parent construct's logical-ID churn (the same leak
+        // class fixed for SQS). Durable topics opt into RETAIN via props.removalPolicy.
+        this.topic.applyRemovalPolicy(toRemovalPolicy(props.removalPolicy ?? "DESTROY"));
         new CfnOutput(this, `${id}TopicArn`, {
             key: `${id}TopicArn`,
             value: this.topic.topicArn,

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

@@ -60,6 +60,12 @@ export interface SQSQueueProps {
     contentBasedDeduplication?: boolean;
     fifoThroughputLimit?: "perQueue" | "perMessageGroupId";
     deduplicationScope?: "queue" | "messageGroup";
+    /**
+     * Removal policy for the queue (and its auto-created DLQ, which tracks it).
+     * Defaults to DESTROY — a queue is a transient work medium (see the
+     * constructor). Pass "RETAIN" only for a queue whose contents are
+     * irreplaceable and must survive stack deletion.
+     */
     removalPolicy?: RemovalPolicyString;
 }
 export declare class SQSQueue extends Construct {

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

@@ -83,6 +83,14 @@ export class SQSQueue extends Construct {
         this.id = id;
         // Sanitise id for CloudFormation output keys (must be alphanumeric)
         const outputName = toPascalCase(id);
+        // SQS queues are transient work mediums: their contents (job messages,
+        // failed-delivery copies) regenerate from a source of truth held elsewhere
+        // (Postgres, the producing schedule/rule), so the wrapper defaults to
+        // DESTROY — deliberately NOT the env-aware production->RETAIN of
+        // data-bearing wrappers (S3, EventBus). RETAIN here buys no protection and
+        // orphans the queue on a parent construct's logical-ID churn (the prod
+        // orphan leak). Durable queues opt into RETAIN via props.removalPolicy.
+        const resolvedRemovalPolicy = toRemovalPolicy(props.removalPolicy ?? "DESTROY");
         const isFifo = props.queueType === "fifo";
         const queueName = props.queueName
             ? isFifo
@@ -110,7 +118,7 @@ export class SQSQueue extends Construct {
                     fifo: isFifo,
                     encryption: toEncryption(props.encryption),
                     retentionPeriod: Duration.days(SQS_LIMITS.DEAD_LETTER_QUEUE.DEFAULT_RETENTION_DAYS),
-                    removalPolicy: toRemovalPolicy(props.removalPolicy)
+                    removalPolicy: resolvedRemovalPolicy
                 });
                 deadLetterQueue = {
                     queue: this.dlq,
@@ -156,7 +164,7 @@ export class SQSQueue extends Construct {
             deduplicationScope: isFifo
                 ? toDeduplicationScope(props.deduplicationScope)
                 : undefined,
-            removalPolicy: toRemovalPolicy(props.removalPolicy)
+            removalPolicy: resolvedRemovalPolicy
         });
         new CfnOutput(this, `${outputName}QueueUrl`, {
             key: `${outputName}QueueUrl`,

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.16.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.16.0",
-    "@fjall/util": "^2.16.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": "2383b19f1e7db980ae603a6c75dca2c61b7a1d42"
+  "gitHead": "37008ca5469398c42a09e6babc8cc4192ab938b2"
 }