@fjall/components-infrastructure 9.0.0 → 10.1.2

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

@@ -11,10 +11,28 @@ import type { EcsConstructContext } from "./ecsContext.js";
  * `DeploymentCircuitBreaker` shape. `undefined` resolves to the safe default
  * `{ enable: true, rollback: true }`; `false` resolves to `undefined` (CDK
  * omits the breaker block from CFN output entirely).
+ *
+ * Covers only the halves the L2 type can express (`enable`/`rollback`);
+ * `resetOnHealthyTask` and `threshold` land via
+ * {@link applyCircuitBreakerHardening} on the synthesised L1.
  */
-export declare function resolveCircuitBreaker(config: false | {
-    rollback?: boolean;
-} | undefined): DeploymentCircuitBreaker | undefined;
+export declare function resolveCircuitBreaker(config: EcsServiceProps["circuitBreaker"] | undefined): DeploymentCircuitBreaker | undefined;
+/**
+ * Applies the breaker properties CDK's L2 `DeploymentCircuitBreaker` type
+ * cannot express, via property overrides on the synthesised `CfnService`:
+ *
+ * - `ResetOnHealthyTask` defaults to `false` — deliberately stricter than
+ *   AWS's `true` default, where any one healthy task resets the failure
+ *   counter and a slow crash loop that occasionally boots can hold a
+ *   deployment `IN_PROGRESS` indefinitely.
+ * - `ThresholdConfiguration { Type: COUNT }` when `threshold` is set —
+ *   an absolute failed-task count is the comprehensible shape for the
+ *   low-desired-count workers this hardening exists for.
+ *
+ * No-op when the breaker is disabled (`config === false`) — CFN rejects
+ * breaker sub-properties without an enclosing breaker block.
+ */
+export declare function applyCircuitBreakerHardening(service: FargateService | Ec2Service, config: EcsServiceProps["circuitBreaker"] | undefined): void;
 /** Mutable state for ASG capacity provider deduplication, keyed by SLOT. */
 export interface AsgCapacityState {
     providers: Map<string, AsgCapacityProvider>;
@@ -27,6 +45,14 @@ export interface AsgCapacityState {
     asgOrigins: Map<string, Ec2AsgOrigin>;
     autoScalingGroup?: AutoScalingGroup;
     asgSecurityGroup?: ISecurityGroup;
+    /**
+     * Every capacity slot's instance security group (deduped — a cluster-level
+     * `securityGroup` is shared across slots). Consumers that must reach tasks
+     * regardless of which slot's instances they land on (EventBridge scheduled
+     * tasks place unconstrained across capacity providers) use this, not the
+     * first-wins singular field above.
+     */
+    asgSecurityGroups: ISecurityGroup[];
 }
 export { getEc2ConfigKey, validateSharedEc2CapacityConfig, type Ec2AsgOrigin, type SharedEc2CapacityServiceInput } from "./ecsCapacityConfig.js";
 /**

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

@@ -22,6 +22,10 @@ import { isServiceFargate, isServiceEc2 } from "./ecsTaskDefinition.js";
  * `DeploymentCircuitBreaker` shape. `undefined` resolves to the safe default
  * `{ enable: true, rollback: true }`; `false` resolves to `undefined` (CDK
  * omits the breaker block from CFN output entirely).
+ *
+ * Covers only the halves the L2 type can express (`enable`/`rollback`);
+ * `resetOnHealthyTask` and `threshold` land via
+ * {@link applyCircuitBreakerHardening} on the synthesised L1.
  */
 export function resolveCircuitBreaker(config) {
     if (config === false)
@@ -29,6 +33,30 @@ export function resolveCircuitBreaker(config) {
     const rollback = config?.rollback ?? true;
     return { enable: true, rollback };
 }
+/**
+ * Applies the breaker properties CDK's L2 `DeploymentCircuitBreaker` type
+ * cannot express, via property overrides on the synthesised `CfnService`:
+ *
+ * - `ResetOnHealthyTask` defaults to `false` — deliberately stricter than
+ *   AWS's `true` default, where any one healthy task resets the failure
+ *   counter and a slow crash loop that occasionally boots can hold a
+ *   deployment `IN_PROGRESS` indefinitely.
+ * - `ThresholdConfiguration { Type: COUNT }` when `threshold` is set —
+ *   an absolute failed-task count is the comprehensible shape for the
+ *   low-desired-count workers this hardening exists for.
+ *
+ * No-op when the breaker is disabled (`config === false`) — CFN rejects
+ * breaker sub-properties without an enclosing breaker block.
+ */
+export function applyCircuitBreakerHardening(service, config) {
+    if (config === false)
+        return;
+    const cfnService = service.node.defaultChild;
+    cfnService.addPropertyOverride("DeploymentConfiguration.DeploymentCircuitBreaker.ResetOnHealthyTask", config?.resetOnHealthyTask ?? false);
+    if (config?.threshold !== undefined) {
+        cfnService.addPropertyOverride("DeploymentConfiguration.DeploymentCircuitBreaker.ThresholdConfiguration", { Type: "COUNT", Value: config.threshold });
+    }
+}
 export { getEc2ConfigKey, validateSharedEc2CapacityConfig } from "./ecsCapacityConfig.js";
 /**
  * Gets or creates an ASG capacity provider for an EC2-backed service.
@@ -196,6 +224,9 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
     if (!state.asgSecurityGroup) {
         state.asgSecurityGroup = asgSecurityGroup;
     }
+    if (!state.asgSecurityGroups.includes(asgSecurityGroup)) {
+        state.asgSecurityGroups.push(asgSecurityGroup);
+    }
     return provider;
 }
 /**
@@ -268,6 +299,7 @@ export function createService(ctx, serviceName, serviceProps, taskDefinition, as
             })
         });
     }
+    applyCircuitBreakerHardening(service, serviceProps.circuitBreaker);
     if (serviceProps.cloudMapService !== undefined) {
         const isSrv = serviceProps.cloudMapDnsRecordType === "SRV";
         const isHostOrBridge = taskDefinition.networkMode === NetworkMode.HOST ||

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

@@ -3,6 +3,7 @@ import { Duration } from "aws-cdk-lib";
 import { Secret as EcsSecret } from "aws-cdk-lib/aws-ecs";
 import { StringParameter } from "aws-cdk-lib/aws-ssm";
 import { buildParameterPath } from "@fjall/util";
+import { DEFAULT_ALB_IDLE_TIMEOUT_SECONDS, FJALL_ALB_IDLE_TIMEOUT_ENV_VAR } from "@fjall/util/httpKeepAlive";
 import { resolveOrgId } from "../../../utils/cdkContext.js";
 import { validateSsmPathComponent, validateSecretName } from "./ecsValidation.js";
 import { DEFAULT_LOG_RETENTION, DEFAULT_FARGATE_CPU, DEFAULT_FARGATE_MEMORY_MIB, resolveEc2ContainerMemoryMiB } from "./ecsConstants.js";
@@ -194,6 +195,14 @@ export function addContainersToTask(ctx, serviceName, serviceProps, taskDefiniti
                 ...remoteEnv,
                 ...(containerConfig.port
                     ? { PORT: String(containerConfig.port) }
+                    : {}),
+                // The ALB half of the keep-alive contract (@fjall/util/httpKeepAlive):
+                // only the first port-bearing container is ALB-registered, and the
+                // value must match the idleTimeout pinned in applicationLoadBalancer.ts.
+                ...(isFirstWithPort && !ctx.loadBalancerDisabled
+                    ? {
+                        [FJALL_ALB_IDLE_TIMEOUT_ENV_VAR]: String(DEFAULT_ALB_IDLE_TIMEOUT_SECONDS)
+                    }
                     : {})
             },
             secrets,
@@ -218,6 +227,9 @@ export function addContainersToTask(ctx, serviceName, serviceProps, taskDefiniti
             stopTimeout: containerConfig.stopTimeout !== undefined
                 ? Duration.seconds(containerConfig.stopTimeout)
                 : undefined,
+            startTimeout: containerConfig.startTimeout !== undefined
+                ? Duration.seconds(containerConfig.startTimeout)
+                : undefined,
             ...(isServiceEc2(serviceProps) && {
                 memoryLimitMiB: resolveEc2ContainerMemoryMiB(serviceProps.ec2Config)
             })

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

@@ -334,6 +334,15 @@ export interface EcsClusterContainerConfig {
      * - Repository: CDK ECR Repository construct
      */
     image?: string | Repository;
+    /**
+     * When true, a string `image` is always rendered verbatim via
+     * `ContainerImage.fromRegistry` — never interpreted as an ECR repository
+     * name with the deploy-managed `<Service>ImageTag` parameter appended.
+     * Set by the patterns layer for synthetic containers whose image is
+     * release-pinned (the schema gate); the registry-URL heuristic in
+     * `getContainerImage` cannot recognise arbitrary custom registry hosts.
+     */
+    verbatimImage?: boolean;
     /**
      * Port the container listens on.
      * The first container with a port becomes the **primary container**
@@ -366,7 +375,10 @@ export interface EcsClusterContainerConfig {
     essential?: boolean;
     /**
      * Health check configuration.
-     * Default: For primary container with port, uses curl health check.
+     * Default: none — the construct emits no container health check unless one
+     * is declared here. Without one (and without an ALB target group), ECS
+     * treats the container as healthy from the moment it is RUNNING, so
+     * post-start exits are invisible to the deployment circuit breaker.
      */
     healthCheck?: {
         command: string[];
@@ -401,6 +413,13 @@ export interface EcsClusterContainerConfig {
      * SIGTERM before sending SIGKILL. Range 1–120. Default: ECS default (30s).
      */
     stopTimeout?: number;
+    /**
+     * Time (seconds) dependents of THIS container wait for it to reach their
+     * declared `dependsOn` condition before giving up (which stops the task
+     * pre-RUNNING). Declared on the depended-on container, per ECS semantics.
+     * Default: none on Fargate; the agent's 3-minute default on EC2.
+     */
+    startTimeout?: number;
 }
 /**
  * Cluster-level configuration.
@@ -609,14 +628,25 @@ export interface EcsServiceProps {
     logMetricNamespace?: string;
     /**
      * Deployment circuit breaker policy.
-     * - undefined (default): `{ enable: true, rollback: true }`
+     * - undefined (default): `{ enable: true, rollback: true }` with
+     *   `resetOnHealthyTask: false`
      * - `false`: disabled entirely (no breaker)
      * - `{ rollback: boolean }`: override rollback behaviour
+     * - `resetOnHealthyTask` (default `false` — deliberately stricter than
+     *   AWS's `true` default): when `true`, any one healthy task resets the
+     *   breaker's failure counter, so a slow crash loop that occasionally
+     *   boots can hold a deployment `IN_PROGRESS` indefinitely.
+     * - `threshold`: absolute failed-task count before the breaker trips
+     *   (CFN `ThresholdConfiguration { Type: COUNT }`). Omitted → ECS computes
+     *   its default from the desired count. Must be a positive integer
+     *   (enforced by `validateEcsClusterProps`).
      *
      * @see https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-circuit-breaker.html
      */
     circuitBreaker?: false | {
         rollback?: boolean;
+        resetOnHealthyTask?: boolean;
+        threshold?: number;
     };
     /**
      * Rolling-deploy capacity bounds. Overrides the default
@@ -698,6 +728,16 @@ export interface EcsClusterProps {
     alertsTopic?: ITopic;
     /** Application ID for alarm tagging (used by webhook to map alarms to applications). */
     applicationId?: string;
+    /**
+     * ECS task-stop watchdog (default on): a per-cluster EventBridge rule
+     * captures abnormal task stops into a 30-day forensic log group
+     * `/fjall/<cluster>/task-stops`, derives
+     * `Fjall/ECS StoppedTaskCount{ClusterName,ServiceName}` via a metric
+     * filter, and (when `alertsTopic` is set) raises a notification-only
+     * churn alarm per service. `false` disables the whole watchdog —
+     * auditable opt-out for cost-sensitive clusters.
+     */
+    taskStopWatchdog?: false;
 }
 /**
  * Data tracked for each service in the cluster.

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

@@ -19,6 +19,12 @@ import type { DomainConfig, EcsCapacityProvider, EcsClusterProps } from "./ecsTy
  * `new EcsCluster(...)` consumer cannot pass it — there is no resources-layer
  * code path to validate.
  *
+ * Same applies to `service.serviceType`: the `"web" | "worker"` intent marker
+ * is a patterns-layer field on `EcsServiceConfig` (its honesty check — worker
+ * + port/portMappings/routing → throw — runs in `validateEcsProps`). It is not
+ * a field on `EcsServiceProps`, so a direct `new EcsCluster(...)` consumer
+ * cannot pass it and 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

@@ -24,6 +24,12 @@ import { validateSharedEc2CapacityConfig } from "./ecsCapacityConfig.js";
  * `new EcsCluster(...)` consumer cannot pass it — there is no resources-layer
  * code path to validate.
  *
+ * Same applies to `service.serviceType`: the `"web" | "worker"` intent marker
+ * is a patterns-layer field on `EcsServiceConfig` (its honesty check — worker
+ * + port/portMappings/routing → throw — runs in `validateEcsProps`). It is not
+ * a field on `EcsServiceProps`, so a direct `new EcsCluster(...)` consumer
+ * cannot pass it and there is no resources-layer code path to validate.
+ *
  * @param props - The cluster props to validate
  * @throws Error if validation fails
  */
@@ -124,6 +130,13 @@ export function validateEcsClusterProps(props) {
                 "Provide ec2Config on the service.");
         }
         validateEc2ServiceSizing(service);
+        if (typeof service.circuitBreaker === "object") {
+            const threshold = service.circuitBreaker.threshold;
+            if (threshold !== undefined &&
+                (!Number.isInteger(threshold) || threshold < 1)) {
+                throw new Error(`Service '${service.name}': circuitBreaker.threshold must be a positive integer (got ${threshold}).`);
+            }
+        }
         if (service.deployment !== undefined) {
             const min = service.deployment.minHealthyPercent;
             const max = service.deployment.maxHealthyPercent;

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

@@ -1,4 +1,4 @@
-import { Duration } from "aws-cdk-lib";
+import { Duration, RemovalPolicy } from "aws-cdk-lib";
 import { Connections, type IConnectable, type IVpc } from "aws-cdk-lib/aws-ec2";
 import { DatabaseCluster, type CfnDBCluster, type IClusterEngine } from "aws-cdk-lib/aws-rds";
 import { Construct } from "constructs";
@@ -49,6 +49,12 @@ interface RdsProps {
     isGlobalSecondary?: boolean;
     secretReplicaRegions?: string[];
     deletionProtection?: boolean;
+    /**
+     * Defaults to SNAPSHOT (final snapshot on delete). DESTROY is reserved for
+     * disposable-data clusters (dev substrates) — delete takes the data with it,
+     * no snapshot, no recovery.
+     */
+    removalPolicy?: RemovalPolicy;
     /** ARN or identifier of DB cluster snapshot to restore from */
     snapshotIdentifier?: string;
     /**

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

@@ -180,7 +180,7 @@ export class RdsAurora extends Construct {
             preferredMaintenanceWindow: props.preferredMaintenanceWindow ??
                 RDS_DEFAULTS.PREFERRED_MAINTENANCE_WINDOW,
             port: this.port,
-            removalPolicy: RemovalPolicy.SNAPSHOT,
+            removalPolicy: props.removalPolicy ?? RemovalPolicy.SNAPSHOT,
             deletionProtection: props.deletionProtection ?? true,
             iamAuthentication: true,
             ...(props.serverlessV2MinCapacity !== undefined && {

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

@@ -4,6 +4,7 @@ import type { IFunction } from "aws-cdk-lib/aws-lambda";
 import type { ICluster, TaskDefinition } from "aws-cdk-lib/aws-ecs";
 import { SQSQueue } from "./sqs.js";
 import { EventBridgeBus } from "./eventbridge.js";
+import { LogGroup } from "../logging/logGroup.js";
 import { CodeBuildProject } from "../utilities/codeBuild.js";
 import type { EventBridgeRetryPolicy } from "./eventBridgeRule.js";
 interface LambdaComputeShape {
@@ -33,10 +34,11 @@ export type ScheduleTargetInput = SQSQueue | LambdaComputeShape | EcsScheduleTar
 /**
  * Public input type for `Subscription.target`. Same dispatch convention as
  * `ScheduleTargetInput`. Subscriptions accept `CodeBuildProject` (used by
- * `EcrDefaultImage`) but not `EventBridgeBus` — bus-to-bus replication is
+ * `EcrDefaultImage`) and `LogGroup` (forensic event capture, used by the ECS
+ * task-stop watchdog) but not `EventBridgeBus` — bus-to-bus replication is
  * not a subscription shape.
  */
-export type SubscriptionTargetInput = SQSQueue | LambdaComputeShape | EcsScheduleTarget | CodeBuildProject;
+export type SubscriptionTargetInput = SQSQueue | LambdaComputeShape | EcsScheduleTarget | CodeBuildProject | LogGroup;
 /**
  * Internal resolve input — the union of every shape `resolveTarget(...)` can
  * dispatch over. `Schedule` and `Subscription` narrow this at the public

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

@@ -1,7 +1,10 @@
 import { EventField, RuleTargetInput } from "aws-cdk-lib/aws-events";
-import { SqsQueue as SqsTarget, LambdaFunction as LambdaTarget, EventBus as EventBusTarget, CodeBuildProject as CodeBuildTarget, EcsTask as EcsTaskTarget } from "aws-cdk-lib/aws-events-targets";
+import { ArnFormat, Stack } from "aws-cdk-lib";
+import { Effect, PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
+import { SqsQueue as SqsTarget, LambdaFunction as LambdaTarget, EventBus as EventBusTarget, CodeBuildProject as CodeBuildTarget, EcsTask as EcsTaskTarget, addToDeadLetterQueueResourcePolicy, bindBaseTargetConfig } from "aws-cdk-lib/aws-events-targets";
 import { SQSQueue } from "./sqs.js";
 import { EventBridgeBus } from "./eventbridge.js";
+import { LogGroup } from "../logging/logGroup.js";
 import { CodeBuildProject } from "../utilities/codeBuild.js";
 function isEcsScheduleTarget(target) {
     return (typeof target === "object" &&
@@ -63,13 +66,16 @@ export function resolveTarget(target, options) {
     if (target instanceof CodeBuildProject) {
         return resolveCodeBuildTarget(target, options.messageGroupId, baseProps, targetInput);
     }
+    if (target instanceof LogGroup) {
+        return resolveLogGroupTarget(target, options.messageGroupId, baseProps, targetInput);
+    }
     if (isEcsScheduleTarget(target)) {
         return resolveEcsTarget(target, options.messageGroupId, baseProps, targetInput);
     }
     if (isLambdaCompute(target)) {
         return resolveLambdaTarget(target, options.messageGroupId, baseProps, targetInput);
     }
-    throw new Error(`Unsupported event target: expected SQSQueue/QueueMessaging, LambdaCompute, EventBridgeBus/EventBusMessaging, CodeBuildProject, or { ecs: EcsCompute, serviceName }; received ${describeTarget(target)}`);
+    throw new Error(`Unsupported event target: expected SQSQueue/QueueMessaging, LambdaCompute, EventBridgeBus/EventBusMessaging, CodeBuildProject, LogGroup, or { ecs: EcsCompute, serviceName }; received ${describeTarget(target)}`);
 }
 function resolveQueueTarget(target, messageGroupId, baseProps, targetInput) {
     const queue = target.getQueue();
@@ -135,6 +141,53 @@ function resolveCodeBuildTarget(target, messageGroupId, baseProps, targetInput)
         ...(targetInput !== undefined && { event: targetInput })
     });
 }
+/**
+ * CloudWatch Logs rule target. Hand-rolled rather than CDK's
+ * `CloudWatchLogGroup` adapter: that adapter provisions the log-group resource
+ * policy through a custom-resource Lambda (`LogGroupResourcePolicy`), adding a
+ * Lambda to every consuming stack plus one account-level Logs resource policy
+ * per rule — and account-level policies are hard-capped at 10 per region.
+ * `addToResourcePolicy` synthesises a native `AWS::Logs::ResourcePolicy`
+ * instead: no Lambda, one policy per log group, deduplicated by CDK.
+ *
+ * `payload` is rejected: EventBridge delivers the full matched event JSON as
+ * the log message only when the target carries no input transform, and
+ * downstream metric filters select on `$.detail.*` fields of that JSON — a
+ * transformed message would silently break every selector.
+ */
+function resolveLogGroupTarget(target, messageGroupId, baseProps, targetInput) {
+    rejectMessageGroupIdOnNonQueue("logGroup", messageGroupId);
+    if (targetInput !== undefined) {
+        throw new Error("payload is not supported on log-group event targets — the full matched " +
+            "event JSON must reach the log message untransformed so metric-filter " +
+            "field selectors keep working.");
+    }
+    target.addToResourcePolicy(new PolicyStatement({
+        effect: Effect.ALLOW,
+        actions: ["logs:CreateLogStream", "logs:PutLogEvents"],
+        resources: [target.logGroupArn],
+        principals: [new ServicePrincipal("events.amazonaws.com")]
+    }));
+    return {
+        bind: (rule) => {
+            if (baseProps.deadLetterQueue !== undefined) {
+                addToDeadLetterQueueResourcePolicy(rule, baseProps.deadLetterQueue);
+            }
+            return {
+                ...bindBaseTargetConfig(baseProps),
+                // EventBridge expects the log-group ARN WITHOUT the `:*` suffix that
+                // `logGroupArn` carries.
+                arn: Stack.of(target).formatArn({
+                    service: "logs",
+                    resource: "log-group",
+                    arnFormat: ArnFormat.COLON_RESOURCE_NAME,
+                    resourceName: target.logGroupName
+                }),
+                targetResource: target
+            };
+        }
+    };
+}
 function rejectMessageGroupIdOnNonQueue(kind, messageGroupId) {
     if (messageGroupId !== undefined) {
         throw new Error(`messageGroupId only applies to FIFO queue targets; received on '${kind}' target`);

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

@@ -13,6 +13,7 @@ export declare const ALARM_DEFAULTS: {
         readonly CPU: 80;
         readonly MEMORY: 80;
         readonly RUNNING_TASKS_MIN: 1;
+        readonly STOPPED_TASKS: 3;
     };
     readonly ALB: {
         readonly HTTP_5XX_PERCENT: 5;

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

@@ -7,7 +7,7 @@ import { Duration, Tags } from "aws-cdk-lib";
 export const APPLICATION_ID_TAG_KEY = "fjall:applicationId";
 export const ALARM_DEFAULTS = {
     EVALUATION_PERIOD: Duration.minutes(5),
-    ECS: { CPU: 80, MEMORY: 80, RUNNING_TASKS_MIN: 1 },
+    ECS: { CPU: 80, MEMORY: 80, RUNNING_TASKS_MIN: 1, STOPPED_TASKS: 3 },
     ALB: { HTTP_5XX_PERCENT: 5, P99_RESPONSE_TIME_MS: 3000 },
     RDS: { CPU: 80, FREE_STORAGE_GIB: 5, CONNECTIONS: 50 },
     LAMBDA: { ERROR_RATE: 5, DURATION_PERCENT: 80 },

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

@@ -0,0 +1,59 @@
+import { Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { ICluster } from "aws-cdk-lib/aws-ecs";
+import type { ITopic } from "aws-cdk-lib/aws-sns";
+import type { Construct } from "constructs";
+import { LogGroup } from "../logging/logGroup.js";
+import { Subscription } from "../messaging/subscription.js";
+/**
+ * The abnormal-stop allowlist. `EssentialContainerExited` covers every crash
+ * after the container started (including crash loops); `TaskFailedToStart`
+ * covers image-pull, secret-resolution and dependency-condition failures.
+ * Deliberately excludes `ServiceSchedulerInitiated` (scale-in / deploy drain),
+ * `UserInitiated` (operator StopTask), `SpotInterruption` and
+ * `TerminationNotice` — routine stops that would drown the forensic signal.
+ */
+export declare const ABNORMAL_TASK_STOP_CODES: readonly ["EssentialContainerExited", "TaskFailedToStart"];
+/** Metric emitted into `METRIC_NAMESPACE.ECS` by the watchdog's filter. */
+export declare const TASK_STOP_METRIC_NAME = "StoppedTaskCount";
+export interface EcsTaskStopWatchdogProps {
+    scope: Construct;
+    /** Cluster name — keys construct ids and the forensic log-group path. */
+    clusterName: string;
+    /** Cluster whose `clusterArn` scopes the EventBridge pattern. */
+    cluster: ICluster;
+    /** Steady-state service names to raise per-service churn alarms for. */
+    serviceNames: string[];
+    /** SNS topic for churn alarms. Omitted → forensic capture only, no alarms. */
+    alertsTopic?: ITopic;
+    /** Application ID for alarm tagging (webhook-to-application mapping). */
+    applicationId?: string;
+}
+export interface EcsTaskStopWatchdog {
+    logGroup: LogGroup;
+    subscription: Subscription;
+    alarms: Alarm[];
+}
+/**
+ * ECS task-stop watchdog: the forensic artefact for abnormal task stops.
+ *
+ * A crash-looping service leaves almost no trace once ECS expunges its stopped
+ * tasks (~1 hour) — the 2026-08-09 incident produced 69 task deaths with no
+ * durable record and no notification. This watchdog captures every abnormal
+ * stop event (`stopCode` allowlist above) for one cluster into a 30-day log
+ * group `/fjall/<cluster>/task-stops` via a default-bus EventBridge rule, then
+ * derives `Fjall/ECS StoppedTaskCount{ClusterName,ServiceName}` through a
+ * metric filter and raises a notification-only churn alarm per service.
+ *
+ * Dimension values are what the raw event carries: `ClusterName` is the full
+ * cluster ARN and `ServiceName` is the deployment group (`service:<name>`) —
+ * metric-filter dimensions can only select JSON fields, never rewrite them.
+ * The filter also drops `family:*` groups (standalone/scheduled tasks), whose
+ * stops still land in the log group for forensics but carry no service to
+ * alarm on.
+ *
+ * The rule attaches to the account default bus (AWS service events fire only
+ * there), so the `Subscription` is constructed directly with no `eventBus` —
+ * the `fromAwsServiceBus` guard exists to stop `aws.*` subscriptions on custom
+ * app buses, a misuse this resources-layer composition cannot express.
+ */
+export declare function createEcsTaskStopWatchdog(props: EcsTaskStopWatchdogProps): EcsTaskStopWatchdog;

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

@@ -0,0 +1,115 @@
+import { Alarm, ComparisonOperator, Metric, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+import { SnsAction } from "aws-cdk-lib/aws-cloudwatch-actions";
+import { RemovalPolicy } from "aws-cdk-lib";
+import { FilterPattern, MetricFilter, RetentionDays } from "aws-cdk-lib/aws-logs";
+import { ALARM_DEFAULTS, buildAlarmDescription, registerAlarm, tagAlarmsWithApplicationId } from "./alarmDefaults.js";
+import { METRIC_NAMESPACE } from "./metricNamespaces.js";
+import { LogGroup } from "../logging/logGroup.js";
+import { Subscription } from "../messaging/subscription.js";
+/**
+ * The abnormal-stop allowlist. `EssentialContainerExited` covers every crash
+ * after the container started (including crash loops); `TaskFailedToStart`
+ * covers image-pull, secret-resolution and dependency-condition failures.
+ * Deliberately excludes `ServiceSchedulerInitiated` (scale-in / deploy drain),
+ * `UserInitiated` (operator StopTask), `SpotInterruption` and
+ * `TerminationNotice` — routine stops that would drown the forensic signal.
+ */
+export const ABNORMAL_TASK_STOP_CODES = [
+    "EssentialContainerExited",
+    "TaskFailedToStart"
+];
+/** Metric emitted into `METRIC_NAMESPACE.ECS` by the watchdog's filter. */
+export const TASK_STOP_METRIC_NAME = "StoppedTaskCount";
+/**
+ * ECS deployment-group prefix for service tasks. Coupled between the metric
+ * filter's pattern and the alarm's ServiceName dimension — drift between the
+ * two silently renders every churn alarm dead (metric emitted under one
+ * dimension value, alarm querying another).
+ */
+const SERVICE_GROUP_PREFIX = "service:";
+/**
+ * ECS task-stop watchdog: the forensic artefact for abnormal task stops.
+ *
+ * A crash-looping service leaves almost no trace once ECS expunges its stopped
+ * tasks (~1 hour) — the 2026-08-09 incident produced 69 task deaths with no
+ * durable record and no notification. This watchdog captures every abnormal
+ * stop event (`stopCode` allowlist above) for one cluster into a 30-day log
+ * group `/fjall/<cluster>/task-stops` via a default-bus EventBridge rule, then
+ * derives `Fjall/ECS StoppedTaskCount{ClusterName,ServiceName}` through a
+ * metric filter and raises a notification-only churn alarm per service.
+ *
+ * Dimension values are what the raw event carries: `ClusterName` is the full
+ * cluster ARN and `ServiceName` is the deployment group (`service:<name>`) —
+ * metric-filter dimensions can only select JSON fields, never rewrite them.
+ * The filter also drops `family:*` groups (standalone/scheduled tasks), whose
+ * stops still land in the log group for forensics but carry no service to
+ * alarm on.
+ *
+ * The rule attaches to the account default bus (AWS service events fire only
+ * there), so the `Subscription` is constructed directly with no `eventBus` —
+ * the `fromAwsServiceBus` guard exists to stop `aws.*` subscriptions on custom
+ * app buses, a misuse this resources-layer composition cannot express.
+ */
+export function createEcsTaskStopWatchdog(props) {
+    const { scope, clusterName, cluster, serviceNames, alertsTopic, applicationId } = props;
+    // Fixed-name log group: the env-aware RETAIN default would orphan
+    // `/fjall/<cluster>/task-stops` on stack delete or a `taskStopWatchdog:
+    // false` toggle, and the next synth's CREATE then collides with the
+    // orphan. Rolling 30-day telemetry is not worth bricking redeploys.
+    const logGroup = new LogGroup(scope, `${clusterName}TaskStopsLogGroup`, {
+        logGroupName: `/fjall/${clusterName}/task-stops`,
+        retention: RetentionDays.ONE_MONTH,
+        removalPolicy: RemovalPolicy.DESTROY
+    });
+    const subscription = new Subscription(scope, `${clusterName}TaskStops`, {
+        description: `Forensic capture of abnormal task stops in ECS cluster ${clusterName}`,
+        pattern: {
+            source: ["aws.ecs"],
+            detailType: ["ECS Task State Change"],
+            detail: {
+                clusterArn: [cluster.clusterArn],
+                lastStatus: ["STOPPED"],
+                stopCode: [...ABNORMAL_TASK_STOP_CODES]
+            }
+        },
+        target: logGroup
+    });
+    new MetricFilter(scope, `${clusterName}TaskStopsMetricFilter`, {
+        logGroup,
+        metricNamespace: METRIC_NAMESPACE.ECS,
+        metricName: TASK_STOP_METRIC_NAME,
+        filterPattern: FilterPattern.literal(`{ $.detail.group = "${SERVICE_GROUP_PREFIX}*" }`),
+        metricValue: "1",
+        dimensions: {
+            ClusterName: "$.detail.clusterArn",
+            ServiceName: "$.detail.group"
+        }
+    });
+    const alarms = [];
+    if (alertsTopic === undefined) {
+        return { logGroup, subscription, alarms };
+    }
+    const snsAction = new SnsAction(alertsTopic);
+    for (const serviceName of serviceNames) {
+        const alarm = new Alarm(scope, `${serviceName}TaskStopsAlarm`, {
+            alarmDescription: buildAlarmDescription(`ECS service ${serviceName} abnormal task stops — crash loop or failing deployment`, applicationId),
+            metric: new Metric({
+                namespace: METRIC_NAMESPACE.ECS,
+                metricName: TASK_STOP_METRIC_NAME,
+                period: ALARM_DEFAULTS.EVALUATION_PERIOD,
+                statistic: "Sum",
+                dimensionsMap: {
+                    ClusterName: cluster.clusterArn,
+                    ServiceName: `${SERVICE_GROUP_PREFIX}${serviceName}`
+                }
+            }),
+            threshold: ALARM_DEFAULTS.ECS.STOPPED_TASKS,
+            evaluationPeriods: 1,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+            treatMissingData: TreatMissingData.NOT_BREACHING
+        });
+        registerAlarm(alarm, snsAction, alarms);
+    }
+    tagAlarmsWithApplicationId(alarms, applicationId);
+    return { logGroup, subscription, alarms };
+}

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

@@ -7,4 +7,5 @@ export { createSqsDlqAlarms, type SqsAlarmThresholds, type SqsDlqAlarmsProps } f
 export { createClickHouseAlarms, type ClickHouseAlarmThresholds, type ClickHouseAlarmsProps } from "./clickhouseAlarms.js";
 export { createBuildkiteAlarms, type BuildkiteAlarmsProps } from "./buildkiteAlarms.js";
 export { createLogPatternAlarms, type LogPatternAlarmSpec, type LogPatternAlarmsProps } from "./logPatternAlarms.js";
+export { createEcsTaskStopWatchdog, ABNORMAL_TASK_STOP_CODES, TASK_STOP_METRIC_NAME, type EcsTaskStopWatchdog, type EcsTaskStopWatchdogProps } from "./ecsTaskStopWatchdog.js";
 export { METRIC_NAMESPACE, type MetricNamespace } from "./metricNamespaces.js";

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

@@ -7,4 +7,5 @@ export { createSqsDlqAlarms } from "./sqsAlarms.js";
 export { createClickHouseAlarms } from "./clickhouseAlarms.js";
 export { createBuildkiteAlarms } from "./buildkiteAlarms.js";
 export { createLogPatternAlarms } from "./logPatternAlarms.js";
+export { createEcsTaskStopWatchdog, ABNORMAL_TASK_STOP_CODES, TASK_STOP_METRIC_NAME } from "./ecsTaskStopWatchdog.js";
 export { METRIC_NAMESPACE } from "./metricNamespaces.js";

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

@@ -8,6 +8,7 @@
  */
 export declare const METRIC_NAMESPACE: {
     readonly CLICKHOUSE: "Fjall/ClickHouse";
+    readonly ECS: "Fjall/ECS";
     readonly WEBAPP: "Fjall/WebApp";
 };
 export type MetricNamespace = (typeof METRIC_NAMESPACE)[keyof typeof METRIC_NAMESPACE];

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

@@ -8,5 +8,6 @@
  */
 export const METRIC_NAMESPACE = {
     CLICKHOUSE: "Fjall/ClickHouse",
+    ECS: "Fjall/ECS",
     WEBAPP: "Fjall/WebApp"
 };