@fjall/components-infrastructure 18.0.0 → 19.0.0

package/dist/lib/app.js

@@ -13,6 +13,7 @@ import { BuildkiteFactory } from "./patterns/aws/buildkite.js";
 import { DevSubstrate } from "./patterns/aws/devSubstrate.js";
 import { StandardTagsAspect } from "./utils/standardTagsAspect.js";
 import { emitAppLevelAlbAliasExports } from "./utils/albAliasTargetRegistry.js";
+import { ensureFunctionLogGroups } from "./resources/aws/logging/logGroupHygiene.js";
 import { BACKUP_TIER_TAG_KEY, BACKUP_TIER_TAG_MAP } from "./utils/backupTierMapping.js";
 import { randomBytes } from "crypto";
 import { getConfig } from "./utils/getConfig.js";
@@ -844,6 +845,9 @@ export class App extends CdkApp {
         // Must precede super.synth(): the tree is still mutable here, and only
         // now is the ALB count per app final.
         emitAppLevelAlbAliasExports(this);
+        // Also pre-super, and before aspects run inside it, so the log groups
+        // this creates are still visited by the app-wide tag aspects.
+        ensureFunctionLogGroups(this);
         const assembly = super.synth(options);
         // After synthesis, write Fjall manifest to cdk.out
         try {

package/dist/lib/config/aws/alarmTopic.d.ts

@@ -23,6 +23,26 @@ export interface SharedAlarmTopicProps {
         emails?: string[];
         httpsEndpoints?: string[];
     };
+    /**
+     * Encrypt the topic at rest with a customer-managed KMS key. Off by
+     * default: the key costs $1–3/month per account-region (base + up to two
+     * billed annual rotations), so the accessible
+     * default stays unencrypted and the SNS_TOPIC_NOT_ENCRYPTED posture
+     * finding stands as the signpost to this knob (2026-08-24 dogfood: all 14
+     * of our own findings for that rule were this construct).
+     *
+     * Opting OUT again on production does not delete the key: it is
+     * stack-scoped, so D17 RETAINs it there and the still-billed key becomes
+     * exactly the KMS_KEY_ORPHAN finding class — schedule its deletion
+     * manually after removing the flag.
+     *
+     * Opting in also grants `cloudwatch.amazonaws.com` decrypt/generate on the
+     * key's resource policy — without that, every alarm transition fails
+     * silently at publish and alarms page nobody. The AWS-managed `aws/sns`
+     * key cannot be used for exactly this reason: its policy is immutable, so
+     * CloudWatch can never be admitted.
+     */
+    encrypted?: boolean;
 }
 export declare class SharedAlarmTopic extends Construct {
     readonly topic: ITopic;

package/dist/lib/config/aws/alarmTopic.js

@@ -1,6 +1,8 @@
 import { CfnOutput } from "aws-cdk-lib";
+import { PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
 import { EmailSubscription, UrlSubscription } from "aws-cdk-lib/aws-sns-subscriptions";
 import { Construct } from "constructs";
+import { CustomerManagedKey } from "../../resources/aws/secrets/kms.js";
 import { SNSTopic } from "../../resources/aws/messaging/sns.js";
 /**
  * The well-known cross-stack export name for the account's shared alarm
@@ -14,8 +16,26 @@ export class SharedAlarmTopic extends Construct {
     topicArn;
     constructor(scope, id, props) {
         super(scope, id);
+        let masterKey;
+        if (props?.encrypted === true) {
+            const cmk = new CustomerManagedKey(this, "AlarmTopicKey", {
+                description: "Encrypts the shared CloudWatch alarm notification topic",
+                protects: "stack-scoped"
+            });
+            // CloudWatch publishes alarm transitions through the topic's key; the
+            // exact action pair AWS documents for alarms-to-encrypted-topics. No
+            // aws:SourceAccount condition — CloudWatch does not reliably pass it on
+            // this path, and a mismatch fails silently (alarms page nobody).
+            cmk.key.addToResourcePolicy(new PolicyStatement({
+                principals: [new ServicePrincipal("cloudwatch.amazonaws.com")],
+                actions: ["kms:Decrypt", "kms:GenerateDataKey*"],
+                resources: ["*"]
+            }));
+            masterKey = cmk.key;
+        }
         const wrapped = new SNSTopic(this, "AlarmNotifications", {
-            displayName: "Fjall CloudWatch Alarm Notifications"
+            displayName: "Fjall CloudWatch Alarm Notifications",
+            ...(masterKey !== undefined && { masterKey })
         });
         this.topic = wrapped.getTopic();
         for (const email of props?.subscriptions?.emails ?? []) {

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

@@ -34,6 +34,14 @@ export interface AccountProps extends StackProps {
      * `securityTier`.
      */
     alarmSubscriptions?: SharedAlarmTopicProps["subscriptions"];
+    /**
+     * Encrypt the shared alarm topic at rest with a customer-managed KMS key
+     * ($1–3/month per account-region once rotation accrues). Off by default — the accessible-default
+     * posture; the SNS_TOPIC_NOT_ENCRYPTED finding stands as the signpost to
+     * this knob. Sourced from the generated `account/infrastructure.ts`, same
+     * as `alarmSubscriptions`.
+     */
+    alarmTopicEncryption?: SharedAlarmTopicProps["encrypted"];
     /**
      * §4.4a Step-3 contract knob, forwarded to this account's `OidcConnector`.
      * Absent ⇒ `"expanded"` (the safe shared default — governance trust accepts

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

@@ -51,6 +51,9 @@ export class Account extends Stack {
         new SharedAlarmTopic(this, "AlarmTopic", {
             ...(props.alarmSubscriptions !== undefined && {
                 subscriptions: props.alarmSubscriptions
+            }),
+            ...(props.alarmTopicEncryption !== undefined && {
+                encrypted: props.alarmTopicEncryption
             })
         });
         const isStandaloneAccount = this.constructor === Account;

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

@@ -995,7 +995,8 @@ export class EcsCompute extends Construct {
             alertsTopic: resolvedAlertsTopic,
             applicationId: props.applicationId ??
                 (App.hasInstance() ? App.getInstance().getName() : undefined),
-            ...(props.taskStopWatchdog === false && { taskStopWatchdog: false })
+            ...(props.taskStopWatchdog === false && { taskStopWatchdog: false }),
+            ...(props.containerInsights === true && { containerInsights: true })
         };
         this.ecsCluster = new EcsCluster(this, `${id}Ecs`, ecsProps);
         this.connections = this.ecsCluster.connections;

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

@@ -848,7 +848,7 @@ export interface EcsServiceConfig {
     ssmSecretsPath?: string;
     /**
      * Per-service alarm configuration.
-     * - undefined: use defaults (CPU, memory, running tasks, 5xx if ALB)
+     * - undefined: use defaults (CPU, memory, running tasks, 5xx + p99 response time if ALB)
      * - false: disable alarms for this service
      * - object: override specific thresholds
      */
@@ -1067,6 +1067,14 @@ export interface EcsComputeProps {
      * opt-out for cost-sensitive clusters.
      */
     taskStopWatchdog?: false;
+    /**
+     * CloudWatch Container Insights (default off). Enabling it bills
+     * ~$0.30/metric-month of custom `ECS/ContainerInsights` metrics per cluster
+     * plus performance-log ingestion; nothing in the constructs consumes that
+     * namespace (alarms sit on `AWS/ECS` and `Fjall/ECS`), so it is an explicit
+     * opt-in for clusters whose operators read the per-task console breakdown.
+     */
+    containerInsights?: true;
     /** Application ID for alarm tagging (used by webhook to map alarms to applications). */
     applicationId?: string;
 }

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

@@ -17,6 +17,7 @@ const COMPUTE_PROP_APPLICABILITY = {
     alertsTopic: ["ecs"],
     applicationId: ["ecs"],
     taskStopWatchdog: ["ecs"],
+    containerInsights: ["ecs"],
     deployment: ["lambda"],
     functionUrl: ["lambda"],
     handler: ["lambda"],

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

@@ -266,6 +266,10 @@ export class DevSubstrate extends Construct {
                 // an explicit substrate destroy must not strand the repo (BUG-5's
                 // orphan-repo wedge on rollback).
                 removalPolicy: "DESTROY"
+                // Construct-default untagged-only expiry applies deliberately: slot
+                // task defs pin images by TAG, so nothing a running slot restarts
+                // from is ever untagged — while each same-branch repush orphans its
+                // predecessor as untagged, exactly what the default reclaims.
             });
         }
         // Buildx registry cache for slot builds, named by the same helper as the app
@@ -282,6 +286,9 @@ export class DevSubstrate extends Construct {
         else {
             const slotCacheRepository = new Ecr(this, `${slotEcrId}Cache`, {
                 repositoryName: slotCacheRepositoryName,
+                // Owns its single untagged rule below; the construct default would
+                // add a second untagged selector, which ECR rejects.
+                lifecycle: false,
                 // buildx overwrites the per-repo cache manifest tag on every export.
                 tagMutability: TagMutability.MUTABLE,
                 // Rebuildable cache blobs; pinned so an explicit destroy reclaims the

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

@@ -384,7 +384,9 @@ export default class EcsCluster extends Construct {
         const cluster = new CdkCluster(this, `${props.clusterName}Cluster`, {
             vpc: props.vpc,
             clusterName: props.clusterName,
-            containerInsightsV2: ContainerInsights.ENABLED,
+            containerInsightsV2: props.containerInsights === true
+                ? ContainerInsights.ENABLED
+                : ContainerInsights.DISABLED,
             enableFargateCapacityProviders: needsFargate
         });
         new CfnOutput(this, `${this.outputName}DeployableCluster`, {

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

@@ -618,7 +618,7 @@ export interface EcsServiceProps {
     docker?: DockerBuild;
     /**
      * Per-service alarm configuration.
-     * - undefined: use defaults (CPU, memory, running tasks, 5xx if ALB)
+     * - undefined: use defaults (CPU, memory, running tasks, 5xx + p99 response time if ALB)
      * - false: disable alarms for this service
      * - object: override specific thresholds
      */
@@ -748,6 +748,14 @@ export interface EcsClusterProps {
      * auditable opt-out for cost-sensitive clusters.
      */
     taskStopWatchdog?: false;
+    /**
+     * CloudWatch Container Insights (default off). Enabling it bills
+     * ~$0.30/metric-month of custom `ECS/ContainerInsights` metrics per cluster
+     * plus performance-log ingestion; nothing in the constructs consumes that
+     * namespace (alarms sit on `AWS/ECS` and `Fjall/ECS`), so it is an explicit
+     * opt-in for clusters whose operators read the per-task console breakdown.
+     */
+    containerInsights?: true;
 }
 /**
  * Data tracked for each service in the cluster.

package/dist/lib/resources/aws/logging/logGroupHygiene.d.ts

@@ -0,0 +1,35 @@
+import { type IConstruct } from "constructs";
+/**
+ * Give every Lambda function in the tree an explicit, retention-capped log
+ * group.
+ *
+ * Fjall's own lambda constructs already pass `logGroup:` at creation, but
+ * aws-cdk-lib plants handler functions of its own the wrappers never see —
+ * custom-resource providers, bucket-notification handlers, cross-account
+ * zone-delegation singletons, the `AWS679f53fac` SDK-call framework. Left
+ * alone, each of those logs to a runtime-created group with NO retention
+ * (never-expire, billed forever) that is absent from the template and so
+ * survives stack teardown as an orphan. The 2026-08-24 posture dogfood found
+ * 73 such groups across our own six accounts
+ * (`CLOUDWATCH_LOG_RETENTION_MISSING`) and 12 orphaned by torn-down stacks
+ * (`ORPHANED_LAMBDA_LOG_GROUP`).
+ *
+ * For every `AWS::Lambda::Function` with no `loggingConfig`, this pass
+ * creates a sibling {@link LogGroup} (framework retention default, env-aware
+ * removal policy) and points the function at it, so the group lives IN the
+ * template: retention is capped, and teardown takes the group with the stack.
+ * A function that already carries a `loggingConfig` — every function built
+ * through Fjall's wrappers, or any explicit caller choice — is left alone.
+ *
+ * Runs as a pre-synth tree pass from `App.synth()`, not an Aspect: a
+ * construct added mid-aspect-traversal is skipped by the remaining aspects,
+ * so an Aspect-created group would silently miss the app-wide tag aspects.
+ * Runs once per root: the cross-region export reader/writer providers are
+ * planted DURING `super.synth()`, after any user hook can reach them — they
+ * keep their runtime-created groups (the one known gap), and re-running on a
+ * repeated `synth()` would trip `ConstructTreeModifiedAfterSynth` trying to
+ * cover them. Declared `AWS::Logs::LogGroup` resources are deliberately NOT touched — at
+ * the CFN layer an explicit `RetentionDays.INFINITE` choice renders as an
+ * absent `retentionInDays`, indistinguishable from an unset default.
+ */
+export declare function ensureFunctionLogGroups(root: IConstruct): void;

package/dist/lib/resources/aws/logging/logGroupHygiene.js

@@ -0,0 +1,78 @@
+import { CfnResource } from "aws-cdk-lib";
+import { DEFAULT_FRAMEWORK_LOG_RETENTION, LogGroup } from "./logGroup.js";
+const HYGIENE_LOG_GROUP_ID_SUFFIX = "FjallLogs";
+const processedRoots = new WeakSet();
+/**
+ * Give every Lambda function in the tree an explicit, retention-capped log
+ * group.
+ *
+ * Fjall's own lambda constructs already pass `logGroup:` at creation, but
+ * aws-cdk-lib plants handler functions of its own the wrappers never see —
+ * custom-resource providers, bucket-notification handlers, cross-account
+ * zone-delegation singletons, the `AWS679f53fac` SDK-call framework. Left
+ * alone, each of those logs to a runtime-created group with NO retention
+ * (never-expire, billed forever) that is absent from the template and so
+ * survives stack teardown as an orphan. The 2026-08-24 posture dogfood found
+ * 73 such groups across our own six accounts
+ * (`CLOUDWATCH_LOG_RETENTION_MISSING`) and 12 orphaned by torn-down stacks
+ * (`ORPHANED_LAMBDA_LOG_GROUP`).
+ *
+ * For every `AWS::Lambda::Function` with no `loggingConfig`, this pass
+ * creates a sibling {@link LogGroup} (framework retention default, env-aware
+ * removal policy) and points the function at it, so the group lives IN the
+ * template: retention is capped, and teardown takes the group with the stack.
+ * A function that already carries a `loggingConfig` — every function built
+ * through Fjall's wrappers, or any explicit caller choice — is left alone.
+ *
+ * Runs as a pre-synth tree pass from `App.synth()`, not an Aspect: a
+ * construct added mid-aspect-traversal is skipped by the remaining aspects,
+ * so an Aspect-created group would silently miss the app-wide tag aspects.
+ * Runs once per root: the cross-region export reader/writer providers are
+ * planted DURING `super.synth()`, after any user hook can reach them — they
+ * keep their runtime-created groups (the one known gap), and re-running on a
+ * repeated `synth()` would trip `ConstructTreeModifiedAfterSynth` trying to
+ * cover them. Declared `AWS::Logs::LogGroup` resources are deliberately NOT touched — at
+ * the CFN layer an explicit `RetentionDays.INFINITE` choice renders as an
+ * absent `retentionInDays`, indistinguishable from an unset default.
+ */
+export function ensureFunctionLogGroups(root) {
+    if (processedRoots.has(root)) {
+        return;
+    }
+    processedRoots.add(root);
+    for (const node of root.node.findAll()) {
+        if (!CfnResource.isCfnResource(node) ||
+            node.cfnResourceType !== "AWS::Lambda::Function") {
+            continue;
+        }
+        // Two shapes carry this resource type: a genuine CfnFunction (L1/L2),
+        // and the raw CfnResource the lightweight CustomResourceProvider
+        // framework renders. Only the former has the `loggingConfig` accessor;
+        // the latter cannot express a logging config at all, so unset there is
+        // structural. Prototype probing, not `instanceof` — a duplicate
+        // aws-cdk-lib copy in a consumer tree would fail the instanceof.
+        const isFunction = "loggingConfig" in node;
+        if (isFunction && node.loggingConfig !== undefined) {
+            continue;
+        }
+        const scope = node.node.scope;
+        if (scope === undefined) {
+            continue;
+        }
+        const id = `${node.node.id}${HYGIENE_LOG_GROUP_ID_SUFFIX}`;
+        if (scope.node.tryFindChild(id) !== undefined) {
+            continue;
+        }
+        const group = new LogGroup(scope, id, {
+            retention: DEFAULT_FRAMEWORK_LOG_RETENTION
+        });
+        if (isFunction) {
+            node.loggingConfig = { logGroup: group.logGroupName };
+        }
+        else {
+            node.addPropertyOverride("LoggingConfig", {
+                LogGroup: group.logGroupName
+            });
+        }
+    }
+}

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

@@ -1,4 +1,5 @@
 import { Construct } from "constructs";
+import { type IKey } from "aws-cdk-lib/aws-kms";
 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";
@@ -21,6 +22,19 @@ export interface SNSTopicProps {
      * legacy consumer that cannot verify SHA-256.
      */
     signatureVersion?: "1" | "2";
+    /**
+     * KMS key for server-side encryption at rest. Absent ⇒ unencrypted — the
+     * accessible default (a customer-managed key costs $1–3/month per
+     * account-region once annual rotation accrues), so the
+     * SNS_TOPIC_NOT_ENCRYPTED posture finding stands
+     * as the signpost to this knob rather than being silently pre-paid.
+     *
+     * Every AWS service principal that publishes to the topic needs
+     * `kms:Decrypt` + `kms:GenerateDataKey*` on this key's RESOURCE policy or
+     * its publishes fail silently — the AWS-managed `aws/sns` key cannot be
+     * used for service publishers precisely because its policy is immutable.
+     */
+    masterKey?: IKey;
 }
 export declare class SNSTopic extends Construct {
     readonly id: string;

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

@@ -21,7 +21,8 @@ export class SNSTopic extends Construct {
             contentBasedDeduplication: isFifo
                 ? (props.contentBasedDeduplication ?? true)
                 : undefined,
-            signatureVersion: props.signatureVersion ?? "2"
+            signatureVersion: props.signatureVersion ?? "2",
+            masterKey: props.masterKey
         });
         // 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

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

@@ -16,6 +16,11 @@ export interface EcsServiceAlarmThresholds {
     /** 5xx error-rate % threshold (ALB services only). `false` disables the
      *  5xx alarm; the p99 response-time alarm is unaffected. */
     http5xxThreshold?: number | false;
+    /** p99 response-time threshold in milliseconds (ALB services only). `false`
+     *  disables the p99 alarm — for services dominated by deliberately
+     *  long-lived responses (SSE/streaming), which inflate ALB
+     *  TargetResponseTime without any request being slow. */
+    p99ResponseTimeThresholdMs?: number | false;
 }
 export interface EcsServiceAlarmsProps {
     scope: Construct;

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

@@ -78,20 +78,27 @@ export function createEcsServiceAlarms(props) {
             });
             registerAlarm(http5xxAlarm, snsAction, alarms);
         }
-        const p99Alarm = new Alarm(scope, `${serviceName}P99ResponseTimeAlarm`, {
-            alarmDescription: buildAlarmDescription(`ECS service ${serviceName} p99 response time exceeds threshold`, applicationId),
-            metric: targetGroup.metrics.targetResponseTime({
-                period: ALARM_DEFAULTS.EVALUATION_PERIOD,
-                statistic: "p99"
-            }),
-            // Response time metric is in seconds
-            threshold: ALARM_DEFAULTS.ALB.P99_RESPONSE_TIME_MS / 1000,
-            evaluationPeriods: 2,
-            datapointsToAlarm: 2,
-            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
-            treatMissingData: TreatMissingData.NOT_BREACHING
-        });
-        registerAlarm(p99Alarm, snsAction, alarms);
+        if (config.p99ResponseTimeThresholdMs !== false) {
+            const p99Alarm = new Alarm(scope, `${serviceName}P99ResponseTimeAlarm`, {
+                alarmDescription: buildAlarmDescription(`ECS service ${serviceName} p99 response time exceeds threshold`, applicationId),
+                metric: targetGroup.metrics.targetResponseTime({
+                    period: ALARM_DEFAULTS.EVALUATION_PERIOD,
+                    statistic: "p99"
+                }),
+                // Response time metric is in seconds
+                threshold: (config.p99ResponseTimeThresholdMs ??
+                    ALARM_DEFAULTS.ALB.P99_RESPONSE_TIME_MS) / 1000,
+                // 3-of-3 (15 min sustained), not 2-of-2: at low traffic one
+                // long-lived SSE/streaming response IS the window's p99, so isolated
+                // one-to-two-window spikes are routine and carry no capacity signal.
+                // Only a sustained breach notifies.
+                evaluationPeriods: 3,
+                datapointsToAlarm: 3,
+                comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+                treatMissingData: TreatMissingData.NOT_BREACHING
+            });
+            registerAlarm(p99Alarm, snsAction, alarms);
+        }
     }
     tagAlarmsWithApplicationId(alarms, applicationId);
     return alarms;

package/dist/lib/resources/aws/secrets/kms.d.ts

@@ -19,8 +19,8 @@ interface CustomerManagedKeyProps {
      *   stack leaving a chargeable key behind forever.
      * - `"outlives-stack"` — at least one encrypted resource survives (an RDS
      *   final snapshot under `RemovalPolicy.SNAPSHOT`, a retained audit bucket,
-     *   a backup vault). The key RETAINs in every environment: ~$1/month is not
-     *   a reason to render a surviving snapshot unrestorable.
+     *   a backup vault). The key RETAINs in every environment: $1–3/month is
+     *   not a reason to render a surviving snapshot unrestorable.
      *
      * A caller that knows better may still override with `removalPolicy` — the
      * teardown paths that delete the survivor first legitimately do.

package/dist/lib/resources/aws/secrets/kms.js

@@ -32,6 +32,11 @@ export class CustomerManagedKey extends Construct {
                 : toRemovalPolicy(envAwareRemovalPolicyDefault()));
         this.key = new Key(this, `${id}Key`, {
             description: props.description || `${id} KMS Key`,
+            // Rotation is NOT free: AWS bills +$1/month for each of the first two
+            // rotated key versions (capped there), so a rotated CMK converges on
+            // $3/month — still not a reason to skip rotation on a key guarding
+            // customer data, but the cost claim must stay honest.
+            enableKeyRotation: true,
             removalPolicy,
             // Keyed on the RESOLVED policy: reading props.removalPolicy here meant
             // a key that resolved to DESTROY any other way got no window at all.

package/dist/lib/resources/aws/storage/ecr.d.ts

@@ -1,5 +1,5 @@
 import { type Construct } from "constructs";
-import { Repository, type RepositoryProps, TagMutability } from "aws-cdk-lib/aws-ecr";
+import { type LifecycleRule, Repository, type RepositoryProps, TagMutability } from "aws-cdk-lib/aws-ecr";
 import type App from "../../../app.js";
 import { type StackBuilder } from "../base/awsStack.js";
 interface EcrProps {
@@ -13,13 +13,53 @@ interface EcrProps {
      * takes the repository AND every image in it.
      */
     removalPolicy?: "DESTROY" | "RETAIN";
+    /**
+     * Image-reclaim policy (default `ECR_LIFECYCLE_DEFAULTS`): untagged images
+     * expire after `untaggedRetentionDays`. Every push from CI is one image, so
+     * without a rule a repository grows without bound (fjall.io's own web-app
+     * repo reached 1,473 images / ~55 GB before this default existed). `false`
+     * disables the rule set — callers that add their own rules MUST pass it,
+     * because ECR allows exactly one untagged-selecting rule per policy.
+     */
+    lifecycle?: EcrLifecycle | false;
+}
+export interface EcrLifecycle {
+    /**
+     * OPT-IN count cap: newest tagged images to keep; older ones are expired.
+     * Deliberately NOT part of the default — count expiry is release-blind
+     * (it cannot know which images retained Releases still reference), and the
+     * webapp's release-aware retention janitor treats any `tagStatus: any` +
+     * `imageCountMoreThan` rule as the retired shape it supersedes
+     * (`partitionCountBasedAnyTagRules`, webapp ecrRetentionSweep.ts) and strips it
+     * from release-referenced repositories on monitored accounts. Reach for it
+     * only on repositories outside release monitoring.
+     */
+    maxImageCount?: number;
+    /** Days an untagged image survives (a superseded manifest, a failed push).
+     *  Safe for buildx provenance/SBOM pushes: ECR never expires an image still
+     *  referenced by a live manifest list, so the untagged attestation/platform
+     *  children of a tagged index only become reclaimable once the index goes. */
+    untaggedRetentionDays?: number;
 }
+/**
+ * Untagged-only by default. Tagged-image retention on monitored accounts is
+ * the webapp janitor's job (release-aware: keep-floor, min-age, release
+ * references); a construct-side count rule would both duplicate it blindly
+ * and be stripped by it as the retired count-based shape — taking the
+ * untagged rule down with the policy before the 2026-08 surgical rewrite.
+ */
+export declare const ECR_LIFECYCLE_DEFAULTS: {
+    readonly untaggedRetentionDays: 7;
+};
 export declare class EcrFactory {
     static build(id: string, props?: EcrProps): (app: App, scope: Construct) => Ecr;
 }
 export declare class Ecr extends Repository {
     constructor(scope: Construct, id: string, props?: EcrProps);
     static getRepositoryProps(props?: EcrProps): RepositoryProps;
+    /** Untagged rule first — ECR requires the untagged selector to carry the
+     *  highest priority, and CDK requires the `ANY` rule to carry the lowest. */
+    static lifecycleRules(lifecycle?: EcrLifecycle): LifecycleRule[];
     static build(id: string, props?: EcrProps): (scope: StackBuilder) => Ecr;
 }
 export {};

package/dist/lib/resources/aws/storage/ecr.js

@@ -1,6 +1,16 @@
-import { Repository, TagMutability } from "aws-cdk-lib/aws-ecr";
-import { CfnOutput, RemovalPolicy } from "aws-cdk-lib";
+import { Repository, TagMutability, TagStatus } from "aws-cdk-lib/aws-ecr";
+import { CfnOutput, Duration, RemovalPolicy } from "aws-cdk-lib";
 import { envAwareRemovalPolicyDefault } from "../../../utils/removalPolicy.js";
+/**
+ * Untagged-only by default. Tagged-image retention on monitored accounts is
+ * the webapp janitor's job (release-aware: keep-floor, min-age, release
+ * references); a construct-side count rule would both duplicate it blindly
+ * and be stripped by it as the retired count-based shape — taking the
+ * untagged rule down with the policy before the 2026-08 surgical rewrite.
+ */
+export const ECR_LIFECYCLE_DEFAULTS = {
+    untaggedRetentionDays: 7
+};
 export class EcrFactory {
     static build(id, props) {
         return (app, scope) => {
@@ -35,9 +45,37 @@ export class Ecr extends Repository {
             // delete outright. Gotcha: DESTROY wipes every pushed image, so a
             // redeploy pulls "not found" for any tag the old repository held.
             emptyOnDelete: destroy,
-            removalPolicy: destroy ? RemovalPolicy.DESTROY : RemovalPolicy.RETAIN
+            removalPolicy: destroy ? RemovalPolicy.DESTROY : RemovalPolicy.RETAIN,
+            ...(props?.lifecycle !== false && {
+                lifecycleRules: Ecr.lifecycleRules(props?.lifecycle)
+            })
         };
     }
+    /** Untagged rule first — ECR requires the untagged selector to carry the
+     *  highest priority, and CDK requires the `ANY` rule to carry the lowest. */
+    static lifecycleRules(lifecycle) {
+        const untaggedRetentionDays = lifecycle?.untaggedRetentionDays ??
+            ECR_LIFECYCLE_DEFAULTS.untaggedRetentionDays;
+        const maxImageCount = lifecycle?.maxImageCount;
+        return [
+            {
+                rulePriority: 1,
+                description: `Expire untagged images after ${untaggedRetentionDays} days`,
+                tagStatus: TagStatus.UNTAGGED,
+                maxImageAge: Duration.days(untaggedRetentionDays)
+            },
+            ...(maxImageCount !== undefined
+                ? [
+                    {
+                        rulePriority: 2,
+                        description: `Keep the newest ${maxImageCount} images`,
+                        tagStatus: TagStatus.ANY,
+                        maxImageCount
+                    }
+                ]
+                : [])
+        ];
+    }
     static build(id, props) {
         return (scope) => new Ecr(scope.getStack(), id, props);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "18.0.0",
+  "version": "19.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -80,8 +80,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1098.0",
-    "@fjall/generator": "^18.0.0",
-    "@fjall/util": "^18.0.0",
+    "@fjall/generator": "^19.0.0",
+    "@fjall/util": "^19.0.0",
     "constructs": "^10.7.2"
   },
   "overrides": {