@fjall/components-infrastructure 2.9.1 → 2.12.0

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

@@ -7,13 +7,13 @@ import type { ITopic } from "aws-cdk-lib/aws-sns";
 import { type ConnectionSpec } from "./interfaces/connector.js";
 import { type RemoteConnectionSpec } from "../../resources/aws/compute/ecsRemoteConnections.js";
 import { type EcsRoutingConfig, type EcsContainerDependency } from "../../resources/aws/compute/ecsTypes.js";
-import { ScalingType, type DomainConfig, type EcsCapacityProvider, type Ec2CapacityConfig } from "../../resources/aws/compute/ecs.js";
+import { ScalingType, type DomainConfig, type EcsCapacityProvider, type Ec2CapacityConfig, type QueueScalingConfig } from "../../resources/aws/compute/ecs.js";
 import type { EcsServiceAlarmThresholds } from "../../resources/aws/monitoring/index.js";
 import { type SecretImport } from "../../resources/aws/secrets/index.js";
 import type { DockerBuild } from "@fjall/util/manifest/schemas";
 export type { RemoteConnectionSpec };
 export { ScalingType };
-export type { EcsCapacityProvider, Ec2CapacityConfig };
+export type { EcsCapacityProvider, Ec2CapacityConfig, QueueScalingConfig };
 /**
  * Configuration for ECS capacity providers.
  */
@@ -450,6 +450,12 @@ export interface EcsScalingConfig {
     minCapacity?: number;
     maxCapacity?: number;
     scalingType?: ScalingType;
+    /**
+     * Queue-depth scaling config. REQUIRED when `scalingType` is
+     * `ScalingType.QUEUE`. Lets a `desiredCount: 0` service wake from zero on
+     * SQS backlog (the only scaling mode that does).
+     */
+    queueScaling?: QueueScalingConfig;
 }
 /**
  * Host-bind volume mounted into one or more containers in the same task.

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

@@ -1,21 +1,21 @@
-import { type Environment, Stack, type StackProps } from "aws-cdk-lib";
+import { type Environment } from "aws-cdk-lib";
+import { type Construct } from "constructs";
+import { Account, type AccountProps } from "./account.js";
 import { type CustomPermissionSets } from "../../config/aws/identityCenter.js";
 import { ScpPreset } from "../../config/aws/scpPreset.js";
 import type { ScpPresetProps } from "../../config/aws/scpPreset.js";
 import { OrganisationResource } from "../../resources/aws/organisation/index.js";
-type ExtendedStackProps = Omit<StackProps, "env"> & {
-    env?: Required<Pick<Environment, "region" | "account">> & Partial<Omit<Environment, "region" | "account">>;
-};
 export type AccountsConfig = {
     readonly [key: string]: readonly string[] | string | AccountsConfig;
 };
-export interface OrganisationProps extends ExtendedStackProps {
+export interface OrganisationProps extends AccountProps {
     organisationName: string;
     accounts: AccountsConfig;
     orgEmail: string;
     accountIds?: Record<string, string>;
     identityCenter?: boolean;
     allowedRegions?: string[];
+    env?: Required<Pick<Environment, "region" | "account">> & Partial<Omit<Environment, "region" | "account">>;
 }
 /**
  * Organisation CDK stack.
@@ -27,14 +27,26 @@ export interface OrganisationProps extends ExtendedStackProps {
  * - Identity Centre configuration
  * - Cost allocation tag auto-activation (daily Lambda)
  */
-export declare class Organisation extends Stack {
+export declare class Organisation extends Account {
     readonly organisationType: "organisation";
     private org;
     private accountRefs;
     private accountMap;
     private accountsConfig;
     private identityCenter?;
-    constructor(id: string, props: OrganisationProps);
+    constructor(scope: Construct, id: string, props: OrganisationProps);
+    /**
+     * The organisation root's OIDC deploy connector is owned by the customer-run
+     * Quick-Create CloudFormation stack, never the inherited Account connector.
+     * Returning `false` is also the short-circuit first clause of Account's OIDC
+     * gate, so no `OidcConnector` is synthesised on the root stack.
+     */
+    protected receivesDeployRole(): boolean;
+    /**
+     * The organisation root runs no application workloads, so it needs no
+     * default-ECR-image helper.
+     */
+    protected createsEcrDefaultImage(): boolean;
     private createAccountReferences;
     private setupOrganisationFeatures;
     private setupCostAllocationTagActivator;
@@ -45,4 +57,3 @@ export declare class Organisation extends Stack {
     getAccounts(): Record<string, string>;
     enableScps(props: ScpPresetProps): ScpPreset;
 }
-export {};

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

@@ -1,5 +1,5 @@
-import { Stack } from "aws-cdk-lib";
 import App from "../../app.js";
+import { Account } from "./account.js";
 import { IdentityCenter } from "../../config/aws/identityCenter.js";
 import { ScpPreset } from "../../config/aws/scpPreset.js";
 import { OrganisationResource, OrganisationAccount, CostAllocationTagActivator } from "../../resources/aws/organisation/index.js";
@@ -17,23 +17,20 @@ import { extractAccountNames } from "../../utils/accountsUtils.js";
  * - Identity Centre configuration
  * - Cost allocation tag auto-activation (daily Lambda)
  */
-export class Organisation extends Stack {
+export class Organisation extends Account {
     organisationType = "organisation";
     org;
     accountRefs = [];
     accountMap;
     accountsConfig;
     identityCenter;
-    constructor(id, props) {
+    constructor(scope, id, props) {
         const config = getConfig();
-        const env = props.env ?? {
-            region: config.region,
-            account: config.accountId ?? ""
-        };
-        if (!env.account) {
-            throw new Error("Organisation requires an account ID. Provide it via env.account or ensure CDK context includes accountId.");
+        const accountId = props.accountId ?? props.env?.account ?? config.accountId;
+        if (!accountId) {
+            throw new Error("Organisation requires an account ID. Provide it via env.account, accountId, or ensure CDK context includes accountId.");
         }
-        super(App.getInstance(), id, { ...props, env });
+        super(scope, id, { ...props, accountId });
         // Normalise account map keys to lowercase for case-insensitive lookups.
         // providerAccounts stores names as lowercase; ACCOUNTS config uses PascalCase.
         const rawMap = props.accountIds ?? config.accountIds ?? {};
@@ -57,6 +54,22 @@ export class Organisation extends Stack {
         this.createAccountReferences(props);
         this.setupOrganisationFeatures(props.identityCenter ?? true, managementAccountId);
     }
+    /**
+     * The organisation root's OIDC deploy connector is owned by the customer-run
+     * Quick-Create CloudFormation stack, never the inherited Account connector.
+     * Returning `false` is also the short-circuit first clause of Account's OIDC
+     * gate, so no `OidcConnector` is synthesised on the root stack.
+     */
+    receivesDeployRole() {
+        return false;
+    }
+    /**
+     * The organisation root runs no application workloads, so it needs no
+     * default-ECR-image helper.
+     */
+    createsEcrDefaultImage() {
+        return false;
+    }
     createAccountReferences(props) {
         const allNames = extractAccountNames(props.accounts);
         for (const accountName of allNames) {

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

@@ -1,3 +1,4 @@
+import App from "../../app.js";
 import { Organisation } from "./organisation.js";
 import { Platform } from "./platform.js";
 import { Account } from "./account.js";
@@ -5,7 +6,7 @@ export class OrganisationFactory {
     static build(id, props) {
         switch (props.type) {
             case "organisation":
-                return new Organisation(id, props);
+                return new Organisation(App.getInstance(), id, props);
             case "platform":
                 return (scope) => new Platform(scope, id, props);
             case "account":

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

@@ -10,5 +10,6 @@ export interface PlatformProps extends AccountProps {
 export declare class Platform extends Account {
     readonly organisationType: OrganisationType;
     constructor(scope: Construct, id: string, props: PlatformProps);
+    protected receivesDeployRole(): boolean;
     enableSecurityServicesAdmin(props: SecurityServicesAdminProps): SecurityServicesAdmin;
 }

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

@@ -23,6 +23,9 @@ export class Platform extends Account {
             ipamScope: ipam.privateDefaultScopeId
         });
     }
+    receivesDeployRole() {
+        return true;
+    }
     enableSecurityServicesAdmin(props) {
         return new SecurityServicesAdmin(this, "SecurityServicesAdmin", props);
     }

package/dist/lib/resources/aws/backup/backupVault.js

@@ -8,19 +8,21 @@ export class BackupVault extends Construct {
     vaultName;
     constructor(scope, id, props) {
         super(scope, id);
+        // RETAIN default: a DESTROY-policy vault is silently deleted with the stack.
+        // Callers opt into DESTROY explicitly for ephemeral/dev vaults.
+        const removalPolicy = props.removalPolicy ?? RemovalPolicy.RETAIN;
         const encryptionKey = props.encryptionKey ||
             new CustomerManagedKey(this, `${props.vaultName}Key`, {
                 description: `Encryption key for backup vault ${props.vaultName}`,
                 aliasName: `cmk/backupVault/${props.vaultName}`,
-                removalPolicy: props.removalPolicy
+                removalPolicy
             });
         this.vault = new Vault(this, `${props.vaultName}Vault`, {
             backupVaultName: props.vaultName,
             encryptionKey: encryptionKey.key,
             accessPolicy: props.accessPolicy,
             lockConfiguration: props.lockConfiguration,
-            // TODO: Revert to RemovalPolicy.RETAIN for production
-            removalPolicy: props.removalPolicy || RemovalPolicy.DESTROY
+            removalPolicy
         });
         this.vaultArn = new CfnOutput(this, `${props.vaultName}VaultArn`, {
             key: `${props.vaultName}VaultArn`,

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

@@ -1,7 +1,7 @@
 import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
 export declare const DEFAULT_EC2_INSTANCE_TYPE = "t4g.micro";
 export declare const DEFAULT_WARM_POOL_MIN_SIZE = 1;
-export declare const DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN = true;
+export declare const DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN = false;
 export declare const DEFAULT_LOG_RETENTION_DAYS = 14;
 export declare const DEFAULT_FARGATE_CPU = 256;
 export declare const DEFAULT_FARGATE_MEMORY_MIB = 512;

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

@@ -2,7 +2,10 @@ import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
 // Canonical source: @fjall/generator schemas/constants.ts — keep in sync
 export const DEFAULT_EC2_INSTANCE_TYPE = "t4g.micro";
 export const DEFAULT_WARM_POOL_MIN_SIZE = 1;
-export const DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN = true;
+// reuseOnScaleIn: true returns scaled-in instances to the warm pool Stopped,
+// which can strand ECS tasks DRAINING indefinitely (the 2026-06-04 outage).
+// Default false — terminate on scale-in. Mirrors the @fjall/generator twin.
+export const DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN = false;
 // 14 days balances cost against retaining enough history for post-mortem debugging
 export const DEFAULT_LOG_RETENTION_DAYS = 14;
 // Smallest valid (cpu, memory) pair on the Fargate matrix — must move together.

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

@@ -30,10 +30,10 @@ export class EcsLifecycleHookMigration extends Construct {
         const migrationTaskDef = props.migrationTaskDef;
         const targetTaskDefinitionArn = migrationTaskDef?.definitionArn ?? props.taskDefinitionArn;
         const runTaskResources = [
-            `arn:aws:ecs:${stack.region}:${stack.account}:task-definition/${props.taskDefinitionFamily}:*`
+            `arn:${stack.partition}:ecs:${stack.region}:${stack.account}:task-definition/${props.taskDefinitionFamily}:*`
         ];
         if (migrationTaskDef !== undefined) {
-            runTaskResources.push(`arn:aws:ecs:${stack.region}:${stack.account}:task-definition/${migrationTaskDef.family}:*`);
+            runTaskResources.push(`arn:${stack.partition}:ecs:${stack.region}:${stack.account}:task-definition/${migrationTaskDef.family}:*`);
         }
         const passRoleResources = [props.taskExecutionRoleArn, props.taskRoleArn];
         if (migrationTaskDef !== undefined) {

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

@@ -1,6 +1,6 @@
 import { Stack } from "aws-cdk-lib";
 import { Effect, Policy, PolicyStatement, Role, ServicePrincipal } from "aws-cdk-lib/aws-iam";
-import { collectSecretsManagerSecretNames, deriveSsmSecretsPath } from "./ecsTaskDefinition.js";
+import { deriveSsmSecretsPath } from "./ecsTaskDefinition.js";
 /**
  * Creates the execution role for ECS infrastructure operations.
  * Used by the ECS agent to pull images, write logs, and inject secrets.
@@ -34,18 +34,9 @@ export function createExecutionRole(ctx, serviceName) {
         ],
         resources: [logGroupArn, `${logGroupArn}:*`]
     }));
-    const secretNames = collectSecretsManagerSecretNames(ctx.props, serviceName);
-    if (secretNames.length > 0) {
-        const secretArns = secretNames.map((secretName) => `arn:${partition}:secretsmanager:${region}:${account}:secret:${secretName}-*`);
-        executionRole.addToPolicy(new PolicyStatement({
-            effect: Effect.ALLOW,
-            actions: [
-                "secretsmanager:GetSecretValue",
-                "secretsmanager:DescribeSecret"
-            ],
-            resources: secretArns
-        }));
-    }
+    // Gotcha: do NOT add a manual `secretsImport` grant here. `addContainer({ secrets })`
+    // auto-grants `secret.grantRead(executionRole)` on the resolved complete ARN (exact, no
+    // wildcard). A manual bare/`-*` statement is the 2026-06-04 outage shape and is dead.
     const serviceProps = ctx.props.services.find((s) => s.name === serviceName);
     const hasSsmSecrets = serviceProps?.containers.some((container) => container.secrets && container.secrets.length > 0) ?? false;
     if (hasSsmSecrets && serviceProps) {

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

@@ -1,7 +1,7 @@
 import { FargateService, Ec2Service, AsgCapacityProvider, type DeploymentCircuitBreaker } from "aws-cdk-lib/aws-ecs";
 import type { FargateTaskDefinition, Ec2TaskDefinition } from "aws-cdk-lib/aws-ecs";
 import { type ISecurityGroup } from "aws-cdk-lib/aws-ec2";
-import { TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
+import { TargetTrackingScalingPolicy, type StepScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
 import { type AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
 import { type EcsServiceProps, type Ec2CapacityConfig } from "./ecsTypes.js";
 import type { EcsConstructContext } from "./ecsContext.js";
@@ -37,6 +37,8 @@ export declare function getOrCreateAsgCapacityProvider(ctx: EcsConstructContext,
  */
 export declare function createService(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps, taskDefinition: FargateTaskDefinition | Ec2TaskDefinition, asgState: AsgCapacityState): FargateService | Ec2Service;
 /**
- * Adds auto-scaling to an ECS service based on CPU or memory utilisation.
+ * Adds auto-scaling to an ECS service. `CPU`/`MEMORY` emit a target-tracking
+ * policy on utilisation; `QUEUE` emits a step-scaling policy on SQS backlog
+ * that can wake the service from `desiredCount: 0`.
  */
-export declare function addServiceScaling(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps, service: FargateService | Ec2Service): TargetTrackingScalingPolicy;
+export declare function addServiceScaling(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps, service: FargateService | Ec2Service): TargetTrackingScalingPolicy | StepScalingPolicy;

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

@@ -3,7 +3,8 @@ import { Peer, Port, SubnetType, UserData } from "aws-cdk-lib/aws-ec2";
 import { ServicePrincipal } from "aws-cdk-lib/aws-iam";
 import { Role } from "../iam/role.js";
 import { CfnOutput, Duration, Token } from "aws-cdk-lib";
-import { PredefinedMetric, ScalableTarget, ServiceNamespace, TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
+import { AdjustmentType, PredefinedMetric, ScalableTarget, ServiceNamespace, TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
+import { MathExpression } from "aws-cdk-lib/aws-cloudwatch";
 import { Monitoring } from "aws-cdk-lib/aws-autoscaling";
 import { SecurityGroup } from "../networking/securityGroup.js";
 import { Ec2Instance } from "./ec2.js";
@@ -282,17 +283,39 @@ export function createService(ctx, serviceName, serviceProps, taskDefinition, as
     return service;
 }
 /**
- * Adds auto-scaling to an ECS service based on CPU or memory utilisation.
+ * Step-scaling intervals on the queue-backlog metric, with
+ * `AdjustmentType.EXACT_CAPACITY` (`change` is the absolute DesiredCount).
+ * Backlog 0 → 0 tasks (wake-to-zero); ≥1 → 1; ≥100 → 2; ≥500 → 3. Capacities
+ * are clamped to the service's `maxCapacity` at build time.
+ */
+const DEFAULT_QUEUE_SCALING_STEPS = [
+    { lower: 0, upper: 1, capacity: 0 },
+    { lower: 1, upper: 100, capacity: 1 },
+    { lower: 100, upper: 500, capacity: 2 },
+    { lower: 500, capacity: 3 }
+];
+const DEFAULT_QUEUE_SCALE_COOLDOWN = Duration.minutes(5);
+/**
+ * Adds auto-scaling to an ECS service. `CPU`/`MEMORY` emit a target-tracking
+ * policy on utilisation; `QUEUE` emits a step-scaling policy on SQS backlog
+ * that can wake the service from `desiredCount: 0`.
  */
 export function addServiceScaling(ctx, serviceName, serviceProps, service) {
     const desiredCount = serviceProps.desiredCount ?? DEFAULT_DESIRED_COUNT;
+    const maxCapacity = serviceProps.maxCapacity ?? Math.max(desiredCount + 1, 3);
     const scalableTarget = new ScalableTarget(ctx.scope, `${serviceName}ScalableTarget`, {
         serviceNamespace: ServiceNamespace.ECS,
         resourceId: `service/${ctx.cluster.clusterName}/${service.serviceName}`,
         scalableDimension: "ecs:service:DesiredCount",
         minCapacity: serviceProps.minCapacity ?? desiredCount,
-        maxCapacity: serviceProps.maxCapacity ?? Math.max(desiredCount + 1, 3)
+        maxCapacity
     });
+    // QUEUE must branch BEFORE the CPU/MEMORY path: it is a mode discriminator
+    // with no predefined metric — falling through would silently emit a CPU
+    // policy on a service that meant to scale on backlog.
+    if (serviceProps.scalingType === ScalingType.QUEUE) {
+        return buildQueueScalingPolicy(serviceName, serviceProps.queueScaling, scalableTarget, maxCapacity);
+    }
     return new TargetTrackingScalingPolicy(ctx.scope, `${serviceName}ScalingPolicy`, {
         scalingTarget: scalableTarget,
         predefinedMetric: serviceProps.scalingType === ScalingType.MEMORY
@@ -303,3 +326,53 @@ export function addServiceScaling(ctx, serviceName, serviceProps, service) {
         scaleOutCooldown: Duration.seconds(60)
     });
 }
+/**
+ * Builds the step-scaling policy for `ScalingType.QUEUE`. The alarm metric is a
+ * `MathExpression` SUM of `ApproximateNumberOfMessagesVisible`
+ * (+`…NotVisible` when `includeInFlight`) across the consumed queues, sampled at
+ * `Maximum` over 1-minute periods — published independent of running-task count,
+ * so the policy fires (and DesiredCount rises from 0) on backlog alone.
+ */
+function buildQueueScalingPolicy(serviceName, config, scalableTarget, maxCapacity) {
+    if (config === undefined || config.queues.length === 0) {
+        throw new Error(`ECS service '${serviceName}' uses ScalingType.QUEUE but provides no queueScaling.queues — at least one queue is required to compute backlog.`);
+    }
+    const includeInFlight = config.includeInFlight ?? true;
+    const usingMetrics = {};
+    const expressionTerms = [];
+    config.queues.forEach((queue, index) => {
+        const visibleId = `visible${index}`;
+        usingMetrics[visibleId] = queue.metricApproximateNumberOfMessagesVisible({
+            statistic: "Maximum",
+            period: Duration.minutes(1)
+        });
+        expressionTerms.push(visibleId);
+        if (includeInFlight) {
+            const inflightId = `inflight${index}`;
+            usingMetrics[inflightId] =
+                queue.metricApproximateNumberOfMessagesNotVisible({
+                    statistic: "Maximum",
+                    period: Duration.minutes(1)
+                });
+            expressionTerms.push(inflightId);
+        }
+    });
+    const backlogMetric = new MathExpression({
+        expression: expressionTerms.join(" + "),
+        usingMetrics,
+        period: Duration.minutes(1),
+        label: `${serviceName}QueueBacklog`
+    });
+    return scalableTarget.scaleOnMetric(`${serviceName}QueueScaling`, {
+        metric: backlogMetric,
+        adjustmentType: AdjustmentType.EXACT_CAPACITY,
+        scalingSteps: DEFAULT_QUEUE_SCALING_STEPS.map((step) => ({
+            lower: step.lower,
+            ...(step.upper !== undefined && { upper: step.upper }),
+            change: Math.min(step.capacity, maxCapacity)
+        })),
+        cooldown: config.cooldown ?? DEFAULT_QUEUE_SCALE_COOLDOWN,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1
+    });
+}

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

@@ -14,11 +14,6 @@ export declare function getServiceCapacityProvider(serviceProps: EcsServiceProps
 export declare function isServiceFargate(serviceProps: EcsServiceProps): boolean;
 /** Checks if a service uses an EC2 capacity provider. */
 export declare function isServiceEc2(serviceProps: EcsServiceProps): boolean;
-/**
- * Collects Secrets Manager secret names from secretsImport for a specific service.
- * Scoped per service to enforce least-privilege on execution roles.
- */
-export declare function collectSecretsManagerSecretNames(props: EcsClusterProps, serviceName: string): string[];
 /**
  * Derives the SSM secrets path for a service.
  * Uses explicit path if provided, otherwise derives from app/cluster/service names.

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

@@ -1,13 +1,13 @@
 import { AwsLogDriver, ContainerDependencyCondition, FargateTaskDefinition, Ec2TaskDefinition, NetworkMode, CpuArchitecture, OperatingSystemFamily } from "aws-cdk-lib/aws-ecs";
 import { Duration } from "aws-cdk-lib";
 import { Secret as EcsSecret } from "aws-cdk-lib/aws-ecs";
-import { Secret } from "aws-cdk-lib/aws-secretsmanager";
 import { StringParameter } from "aws-cdk-lib/aws-ssm";
 import { resolveOrgId } from "../../../utils/cdkContext.js";
 import { validateSsmPathComponent } from "./ecsValidation.js";
 import { DEFAULT_LOG_RETENTION_DAYS, DEFAULT_FARGATE_CPU, DEFAULT_FARGATE_MEMORY_MIB, DEFAULT_EC2_CONTAINER_MEMORY_MIB } from "./ecsConstants.js";
 import { getContainerImage } from "./ecsImages.js";
 import { resolveRemoteConnections } from "./ecsRemoteConnections.js";
+import { resolveImportedSecret } from "../secrets/index.js";
 // Re-export extracted functions so existing consumers are not broken
 export { createExecutionRole, createTaskRole } from "./ecsRoles.js";
 export { getContainerImage } from "./ecsImages.js";
@@ -27,24 +27,6 @@ export function isServiceFargate(serviceProps) {
 export function isServiceEc2(serviceProps) {
     return getServiceCapacityProvider(serviceProps) === "EC2";
 }
-/**
- * Collects Secrets Manager secret names from secretsImport for a specific service.
- * Scoped per service to enforce least-privilege on execution roles.
- */
-export function collectSecretsManagerSecretNames(props, serviceName) {
-    const service = props.services.find((s) => s.name === serviceName);
-    if (!service)
-        return [];
-    const secretNames = new Set();
-    for (const container of service.containers) {
-        if (container.secretsImport) {
-            for (const secretImport of Object.values(container.secretsImport)) {
-                secretNames.add(secretImport.name);
-            }
-        }
-    }
-    return Array.from(secretNames);
-}
 /**
  * Derives the SSM secrets path for a service.
  * Uses explicit path if provided, otherwise derives from app/cluster/service names.
@@ -148,7 +130,7 @@ export function addContainersToTask(ctx, serviceName, serviceProps, taskDefiniti
         const secrets = {};
         if (containerConfig.secretsImport) {
             for (const [key, secretImport] of Object.entries(containerConfig.secretsImport)) {
-                const secret = Secret.fromSecretNameV2(ctx.scope, `${ctx.props.clusterName}${serviceName}${containerConfig.name}${key}Secret`, secretImport.name);
+                const secret = resolveImportedSecret(ctx.scope, `${ctx.props.clusterName}${serviceName}${containerConfig.name}${key}Secret`, secretImport);
                 secrets[key] = EcsSecret.fromSecretsManager(secret, secretImport.field);
             }
         }

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

@@ -4,7 +4,9 @@ import { type Monitoring } from "aws-cdk-lib/aws-autoscaling";
 import { type IService } from "aws-cdk-lib/aws-servicediscovery";
 import { type IManagedPolicy, type PolicyDocument } from "aws-cdk-lib/aws-iam";
 import type { DockerBuild } from "@fjall/util/manifest/schemas";
-import { type TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
+import { type TargetTrackingScalingPolicy, type StepScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
+import { type IQueue } from "aws-cdk-lib/aws-sqs";
+import { type Duration } from "aws-cdk-lib";
 import { type GeoLocation } from "aws-cdk-lib/aws-route53";
 import { type Repository } from "aws-cdk-lib/aws-ecr";
 import { type FargateService, type Ec2Service, type FargateTaskDefinition, type Ec2TaskDefinition } from "aws-cdk-lib/aws-ecs";
@@ -23,9 +25,42 @@ export declare enum Protocol {
     HTTP = 0,
     HTTPS = 1
 }
+/**
+ * Auto-scaling MODE for an ECS service.
+ *
+ * `CPU`/`MEMORY` double as their CDK `PredefinedMetric` value (target-tracking
+ * on utilisation). `QUEUE` is a pure mode discriminator — it has no predefined
+ * metric and drives a step-scaling policy on SQS backlog instead (see
+ * `addServiceScaling` → `buildQueueScalingPolicy`). Treat this as a scaling-MODE
+ * enum, NOT a `PredefinedMetric` alias: a new member must be branched on
+ * explicitly, never fall through the CPU/MEMORY utilisation path.
+ */
 export declare enum ScalingType {
     CPU = "ECSServiceAverageCPUUtilization",
-    MEMORY = "ECSServiceAverageMemoryUtilization"
+    MEMORY = "ECSServiceAverageMemoryUtilization",
+    QUEUE = "QueueBacklog"
+}
+/**
+ * Queue-depth (backlog) scaling configuration for `ScalingType.QUEUE`.
+ *
+ * Drives a step-scaling policy with `AdjustmentType.EXACT_CAPACITY` alarmed on
+ * a `MathExpression` SUM of `ApproximateNumberOfMessagesVisible`
+ * (+`…NotVisible` when `includeInFlight`) across `queues`. The queue-depth
+ * metric publishes every minute independent of running-task count, so the
+ * service wakes from `desiredCount: 0` on backlog — unlike CPU/MEMORY
+ * target-tracking, which has no datapoint at zero tasks.
+ */
+export interface QueueScalingConfig {
+    /** Queues whose combined backlog drives DesiredCount. At least one required. */
+    queues: IQueue[];
+    /**
+     * Include in-flight (received-but-not-deleted) messages in the backlog sum.
+     * Default: true — an in-flight message is still work the service is doing,
+     * so scaling in to zero while messages are in flight would strand them.
+     */
+    includeInFlight?: boolean;
+    /** Cooldown after a scale action. Default: 5 minutes. */
+    cooldown?: Duration;
 }
 import type { EcsCapacityProvider } from "@fjall/generator";
 export type { EcsCapacityProvider };
@@ -301,11 +336,12 @@ export interface EcsServiceProps {
     /** Desired number of tasks. Default: 2 */
     desiredCount?: number;
     /**
-     * Scaling type (CPU or MEMORY). Omit to disable auto-scaling — no
-     * `ScalableTarget` is registered, and `minCapacity`/`maxCapacity` below have
-     * no effect. The `desiredCount: 0 + minCapacity > 0` validation throw still
-     * fires regardless, so operator-intent contradictions surface at synth even
-     * when scaling is disabled.
+     * Scaling mode (`CPU`, `MEMORY`, or `QUEUE`). Omit to disable auto-scaling —
+     * no `ScalableTarget` is registered, and `minCapacity`/`maxCapacity` below
+     * have no effect. The `desiredCount: 0 + minCapacity > 0` validation throw
+     * still fires regardless, so operator-intent contradictions surface at synth
+     * even when scaling is disabled. `QUEUE` additionally requires `queueScaling`
+     * and is the only mode that wakes a `desiredCount: 0` service from zero.
      */
     scalingType?: ScalingType;
     /**
@@ -318,6 +354,12 @@ export interface EcsServiceProps {
      * Only consulted when `scalingType` is set.
      */
     maxCapacity?: number;
+    /**
+     * Queue-depth scaling config. REQUIRED when `scalingType` is
+     * `ScalingType.QUEUE`; ignored otherwise. Lets a `desiredCount: 0` service
+     * wake from zero on SQS backlog.
+     */
+    queueScaling?: QueueScalingConfig;
     /**
      * Routing rules for this service on the cluster's ALB.
      * Required when cluster has multiple services with ports.
@@ -500,5 +542,5 @@ export interface ServiceData {
     containers: ContainerDefinition[];
     primaryContainer?: ContainerDefinition;
     targetGroup?: IApplicationTargetGroup;
-    scalingPolicy?: TargetTrackingScalingPolicy;
+    scalingPolicy?: TargetTrackingScalingPolicy | StepScalingPolicy;
 }

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

@@ -3,8 +3,19 @@ export var Protocol;
     Protocol[Protocol["HTTP"] = 0] = "HTTP";
     Protocol[Protocol["HTTPS"] = 1] = "HTTPS";
 })(Protocol || (Protocol = {}));
+/**
+ * Auto-scaling MODE for an ECS service.
+ *
+ * `CPU`/`MEMORY` double as their CDK `PredefinedMetric` value (target-tracking
+ * on utilisation). `QUEUE` is a pure mode discriminator — it has no predefined
+ * metric and drives a step-scaling policy on SQS backlog instead (see
+ * `addServiceScaling` → `buildQueueScalingPolicy`). Treat this as a scaling-MODE
+ * enum, NOT a `PredefinedMetric` alias: a new member must be branched on
+ * explicitly, never fall through the CPU/MEMORY utilisation path.
+ */
 export var ScalingType;
 (function (ScalingType) {
     ScalingType["CPU"] = "ECSServiceAverageCPUUtilization";
     ScalingType["MEMORY"] = "ECSServiceAverageMemoryUtilization";
+    ScalingType["QUEUE"] = "QueueBacklog";
 })(ScalingType || (ScalingType = {}));

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

@@ -1,4 +1,5 @@
 import { NetworkMode } from "aws-cdk-lib/aws-ecs";
+import { ScalingType } from "./ecsTypes.js";
 /**
  * Validates ECS cluster props before construction.
  * Pure function — does not depend on class state.
@@ -66,6 +67,19 @@ export function validateEcsClusterProps(props) {
                         `stopTimeout must be an integer between 1 and 120 seconds (got ${container.stopTimeout}).`);
                 }
             }
+            // A host-bind volume silently no-ops on Fargate (no host filesystem),
+            // so a /var/run/docker.sock bind for `docker buildx` would fail at
+            // runtime with no synth error. Reject the un-mountable shape at synth.
+            if (service.capacityProvider !== "EC2" && container.volumes) {
+                const hostBind = container.volumes.find((v) => v.hostSourcePath !== undefined);
+                if (hostBind !== undefined) {
+                    throw new Error(`Service '${service.name}', container '${container.name ?? "(default)"}': ` +
+                        `volume '${hostBind.name}' sets hostSourcePath ('${hostBind.hostSourcePath}') but the service uses ` +
+                        `capacityProvider '${service.capacityProvider}'. Host-bind mounts require the EC2 launch type — ` +
+                        "Fargate has no host filesystem, so the mount is silently dropped at deploy (a /var/run/docker.sock " +
+                        "bind for in-container Docker builds would never appear). Set capacityProvider: 'EC2' or remove hostSourcePath.");
+                }
+            }
         }
         if (service.capacityProvider === "EC2" && !service.ec2Config) {
             throw new Error(`Service '${service.name}' uses EC2 capacity provider but no ec2Config is defined. ` +
@@ -97,6 +111,29 @@ export function validateEcsClusterProps(props) {
                 "Application Auto Scaling would immediately scale the service back up, defeating the desiredCount: 0 toggle. " +
                 "Either set scaling.minCapacity to 0 (placeholder service) or raise desiredCount to match scaling.minCapacity.");
         }
+        // A service that starts at zero can only ever come up again on QUEUE
+        // backlog scaling — CPU/MEMORY target-tracking produces no datapoint at
+        // zero running tasks, so DesiredCount never rises (the 2026-06-04
+        // asset-discovery outage). Reject the un-wakeable shape at synth.
+        if (service.desiredCount === 0 &&
+            service.scalingType !== ScalingType.QUEUE) {
+            throw new Error(`Service '${service.name}': desiredCount is 0 but scalingType is ` +
+                `${service.scalingType ?? "unset"} — a service that starts at zero can ` +
+                "only wake on queue backlog. Use ScalingType.QUEUE with queueScaling.queues " +
+                "so it scales up from 0, or raise desiredCount to keep at least one task running. " +
+                "CPU/MEMORY target-tracking produces no datapoint at zero tasks and never scales up.");
+        }
+        if (service.scalingType === ScalingType.QUEUE) {
+            if (service.queueScaling === undefined ||
+                service.queueScaling.queues.length === 0) {
+                throw new Error(`Service '${service.name}': scalingType is ScalingType.QUEUE but provides no ` +
+                    "queueScaling.queues — at least one queue is required to compute backlog.");
+            }
+        }
+        else if (service.queueScaling !== undefined) {
+            throw new Error(`Service '${service.name}': queueScaling is set but scalingType is not ` +
+                "ScalingType.QUEUE — queueScaling only applies to the QUEUE scaling mode.");
+        }
         if (service.capacityProvider === "EC2" &&
             service.securityGroups !== undefined &&
             service.securityGroups.length > 0) {