@emarketeer/ts-microservice-commons 8.2.2 → 9.0.0

package/dist/cdk/cjs/index.js

@@ -4,10 +4,11 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var cdk = require('aws-cdk-lib');
 var awsLambda = require('aws-cdk-lib/aws-lambda');
+var awsIam = require('aws-cdk-lib/aws-iam');
 var awsLogs = require('aws-cdk-lib/aws-logs');
 var constructs = require('constructs');
-var awsIam = require('aws-cdk-lib/aws-iam');
 var awsSsm = require('aws-cdk-lib/aws-ssm');
+var path = require('path');
 var awsDynamodb = require('aws-cdk-lib/aws-dynamodb');
 var awsApigateway = require('aws-cdk-lib/aws-apigateway');
 var awsApigatewayv2 = require('aws-cdk-lib/aws-apigatewayv2');
@@ -21,11 +22,32 @@ var awsEvents = require('aws-cdk-lib/aws-events');
 var awsEventsTargets = require('aws-cdk-lib/aws-events-targets');
 var awsLambdaEventSources = require('aws-cdk-lib/aws-lambda-event-sources');
 var awsCloudwatch = require('aws-cdk-lib/aws-cloudwatch');
-var path = require('path');
 var awsCloudwatchActions = require('aws-cdk-lib/aws-cloudwatch-actions');
 var ec2 = require('aws-cdk-lib/aws-ec2');
 var cxApi = require('aws-cdk-lib/cx-api');
 
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n["default"] = e;
+  return Object.freeze(n);
+}
+
+var cdk__namespace = /*#__PURE__*/_interopNamespace(cdk);
+var path__namespace = /*#__PURE__*/_interopNamespace(path);
+var ec2__namespace = /*#__PURE__*/_interopNamespace(ec2);
+
 /**
  * Stack naming conventions and utilities
  */
@@ -273,39 +295,40 @@ const getLogRetentionDays = (stage) => {
         case 'dev':
             return awsLogs.RetentionDays.THREE_DAYS;
         default:
-            return awsLogs.RetentionDays.ONE_WEEK;
+            // Stage is a compile-time union. A runtime value outside it means a
+            // caller widened the type — fail loud rather than silently returning a
+            // dev-shaped default for what may be a production deployment.
+            throw new Error(`getLogRetentionDays: unknown stage "${stage}"`);
     }
 };
 /**
- * Convert retention days number to RetentionDays enum
+ * Convert retention days number to RetentionDays enum.
+ *
+ * Validates `days` against `RetentionDays`'s TS enum reverse-mapping (every
+ * numeric enum member exposes its name as a string-keyed property — e.g.
+ * `RetentionDays[1] === 'ONE_DAY'`). This catches typos without
+ * hand-maintaining a switch in parallel with the SDK enum.
+ *
+ * `0` is rejected even though `RetentionDays.INFINITE === 0`: passing 0 from
+ * a config object almost always means "unset" rather than "retain forever".
+ * Callers that genuinely want INFINITE must pass `RetentionDays.INFINITE`
+ * explicitly via a non-numeric path (or update this guard with a clear test).
  */
 const convertRetentionDays = (days) => {
-    if (!days)
+    if (days === undefined || days === null)
         return undefined;
-    const retentionMap = {
-        1: awsLogs.RetentionDays.ONE_DAY,
-        3: awsLogs.RetentionDays.THREE_DAYS,
-        5: awsLogs.RetentionDays.FIVE_DAYS,
-        7: awsLogs.RetentionDays.ONE_WEEK,
-        14: awsLogs.RetentionDays.TWO_WEEKS,
-        30: awsLogs.RetentionDays.ONE_MONTH,
-        60: awsLogs.RetentionDays.TWO_MONTHS,
-        90: awsLogs.RetentionDays.THREE_MONTHS,
-        120: awsLogs.RetentionDays.FOUR_MONTHS,
-        150: awsLogs.RetentionDays.FIVE_MONTHS,
-        180: awsLogs.RetentionDays.SIX_MONTHS,
-        365: awsLogs.RetentionDays.ONE_YEAR,
-        400: awsLogs.RetentionDays.THIRTEEN_MONTHS,
-        545: awsLogs.RetentionDays.EIGHTEEN_MONTHS,
-        731: awsLogs.RetentionDays.TWO_YEARS,
-        1827: awsLogs.RetentionDays.FIVE_YEARS,
-        3653: awsLogs.RetentionDays.TEN_YEARS
-    };
-    const result = retentionMap[days];
-    if (!result) {
-        throw new Error(`Unsupported logRetentionDays value: ${days}. Supported values: ${Object.keys(retentionMap).join(', ')}`);
+    if (days === 0) {
+        throw new Error('logRetentionDays: 0 is not accepted (would map to RetentionDays.INFINITE). '
+            + 'Pass RetentionDays.INFINITE explicitly if infinite retention is intended.');
+    }
+    if (typeof awsLogs.RetentionDays[days] !== 'string') {
+        const supported = Object.values(awsLogs.RetentionDays)
+            .filter((v) => typeof v === 'number')
+            .sort((a, b) => a - b)
+            .join(', ');
+        throw new Error(`Unsupported logRetentionDays value: ${days}. Supported values: ${supported}`);
     }
-    return result;
+    return days;
 };
 /**
  * Create a CloudWatch log group with standard configuration
@@ -320,17 +343,6 @@ const createLogGroup = (scope, id, config) => {
         removalPolicy: config.stage === 'prod' ? cdk.RemovalPolicy.RETAIN : cdk.RemovalPolicy.DESTROY
     });
 };
-/**
- * Create a Lambda function log group
- */
-const createLambdaLogGroup = (scope, id, stage, serviceName, functionName, retentionDays) => {
-    const logGroupName = `/aws/lambda/${generateLogGroupName(stage, serviceName, functionName)}`;
-    return createLogGroup(scope, id, {
-        logGroupName,
-        stage,
-        retentionDays
-    });
-};
 /**
  * Create an API Gateway log group
  */
@@ -346,18 +358,20 @@ const createApiGatewayLogGroup = (scope, id, stage, serviceName, apiName, retent
  * Get removal policy based on stage
  */
 const getRemovalPolicy = (stage) => {
-    return stage === 'prod' ? cdk.RemovalPolicy.RETAIN : cdk.RemovalPolicy.DESTROY;
-};
-/**
- * Should enable log insights based on stage
- */
-const shouldEnableLogInsights = (stage) => {
-    return stage === 'prod' || stage === 'staging';
+    switch (stage) {
+        case 'prod':
+            return cdk.RemovalPolicy.RETAIN;
+        case 'staging':
+        case 'test':
+        case 'dev':
+            return cdk.RemovalPolicy.DESTROY;
+        default:
+            // Same rationale as getLogRetentionDays: a typo like 'production' must
+            // not silently produce DESTROY for what should be a retained resource.
+            throw new Error(`getRemovalPolicy: unknown stage "${stage}"`);
+    }
 };
 
-/**
- * IAM role and policy generation helpers
- */
 /**
  * Create a Lambda execution role with standard permissions
  */
@@ -366,115 +380,14 @@ const createLambdaExecutionRole = (scope, id, config) => {
     const role = new awsIam.Role(scope, id, {
         roleName,
         assumedBy: new awsIam.ServicePrincipal('lambda.amazonaws.com'),
-        description: `Lambda execution role for ${config.serviceName}`
+        description: `Lambda execution role for ${config.serviceName}`,
+        ...(config.inlinePolicies && { inlinePolicies: config.inlinePolicies })
     });
-    // Add basic Lambda execution permissions
     role.addManagedPolicy(awsIam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaBasicExecutionRole'));
-    // Add VPC execution permissions if needed
-    if (config.managedPolicies?.includes('AWSLambdaVPCAccessExecutionRole')) {
-        role.addManagedPolicy(awsIam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaVPCAccessExecutionRole'));
-    }
-    return role;
-};
-/**
- * Create a DynamoDB access policy statement
- */
-const createDynamoDBAccessPolicy = (tableArn, actions = [
-    'dynamodb:GetItem',
-    'dynamodb:PutItem',
-    'dynamodb:UpdateItem',
-    'dynamodb:DeleteItem',
-    'dynamodb:Query',
-    'dynamodb:Scan'
-]) => {
-    return new awsIam.PolicyStatement({
-        effect: awsIam.Effect.ALLOW,
-        actions,
-        resources: [tableArn, `${tableArn}/index/*`]
-    });
-};
-/**
- * Create a read-only DynamoDB access policy statement
- */
-const createDynamoDBReadPolicy = (tableArn) => {
-    return createDynamoDBAccessPolicy(tableArn, [
-        'dynamodb:GetItem',
-        'dynamodb:Query',
-        'dynamodb:Scan',
-        'dynamodb:BatchGetItem'
-    ]);
-};
-/**
- * Create a write-only DynamoDB access policy statement
- */
-const createDynamoDBWritePolicy = (tableArn) => {
-    return createDynamoDBAccessPolicy(tableArn, [
-        'dynamodb:PutItem',
-        'dynamodb:UpdateItem',
-        'dynamodb:DeleteItem',
-        'dynamodb:BatchWriteItem'
-    ]);
-};
-/**
- * Create an SQS access policy statement
- */
-const createSQSAccessPolicy = (queueArn, actions = [
-    'sqs:SendMessage',
-    'sqs:ReceiveMessage',
-    'sqs:DeleteMessage',
-    'sqs:GetQueueAttributes'
-]) => {
-    return new awsIam.PolicyStatement({
-        effect: awsIam.Effect.ALLOW,
-        actions,
-        resources: [queueArn]
-    });
-};
-/**
- * Create an SNS publish policy statement
- */
-const createSNSPublishPolicy = (topicArn) => {
-    return new awsIam.PolicyStatement({
-        effect: awsIam.Effect.ALLOW,
-        actions: ['sns:Publish'],
-        resources: [topicArn]
-    });
-};
-/**
- * Create an S3 access policy statement
- */
-const createS3AccessPolicy = (bucketArn, actions = ['s3:GetObject', 's3:PutObject', 's3:DeleteObject']) => {
-    return new awsIam.PolicyStatement({
-        effect: awsIam.Effect.ALLOW,
-        actions,
-        resources: [bucketArn, `${bucketArn}/*`]
-    });
-};
-/**
- * Create an S3 read-only policy statement
- */
-const createS3ReadPolicy = (bucketArn) => {
-    return createS3AccessPolicy(bucketArn, ['s3:GetObject', 's3:ListBucket']);
-};
-/**
- * Create a Secrets Manager access policy statement
- */
-const createSecretsManagerPolicy = (secretArn) => {
-    return new awsIam.PolicyStatement({
-        effect: awsIam.Effect.ALLOW,
-        actions: ['secretsmanager:GetSecretValue', 'secretsmanager:DescribeSecret'],
-        resources: [secretArn]
-    });
-};
-/**
- * Create a Systems Manager Parameter Store access policy statement
- */
-const createSSMParameterPolicy = (parameterArn) => {
-    return new awsIam.PolicyStatement({
-        effect: awsIam.Effect.ALLOW,
-        actions: ['ssm:GetParameter', 'ssm:GetParameters', 'ssm:GetParametersByPath'],
-        resources: [parameterArn]
+    config.managedPolicies?.forEach(policy => {
+        role.addManagedPolicy(policy);
     });
+    return role;
 };
 /**
  * Create an X-Ray tracing policy statement
@@ -486,230 +399,40 @@ const createXRayTracingPolicy = () => {
         resources: ['*']
     });
 };
-/**
- * Create an EventBridge put events policy statement
- */
-const createEventBridgePutEventsPolicy = (eventBusArn) => {
-    return new awsIam.PolicyStatement({
-        effect: awsIam.Effect.ALLOW,
-        actions: ['events:PutEvents'],
-        resources: [eventBusArn]
-    });
-};
-/**
- * Create a CloudWatch Logs policy statement
- */
-const createCloudWatchLogsPolicy = (logGroupArn) => {
-    return new awsIam.PolicyStatement({
-        effect: awsIam.Effect.ALLOW,
-        actions: ['logs:CreateLogGroup', 'logs:CreateLogStream', 'logs:PutLogEvents'],
-        resources: [logGroupArn]
-    });
-};
-/**
- * Create a KMS decrypt policy statement
- */
-const createKMSDecryptPolicy = (keyArn) => {
-    return new awsIam.PolicyStatement({
-        effect: awsIam.Effect.ALLOW,
-        actions: ['kms:Decrypt', 'kms:DescribeKey'],
-        resources: [keyArn]
-    });
-};
-/**
- * Create a Lambda invoke policy statement
- */
-const createLambdaInvokePolicy = (functionArn) => {
-    return new awsIam.PolicyStatement({
-        effect: awsIam.Effect.ALLOW,
-        actions: ['lambda:InvokeFunction'],
-        resources: [functionArn]
-    });
-};
-/**
- * Create a Step Functions start execution policy statement
- */
-const createStepFunctionsExecutionPolicy = (stateMachineArn) => {
-    return new awsIam.PolicyStatement({
-        effect: awsIam.Effect.ALLOW,
-        actions: ['states:StartExecution', 'states:DescribeExecution', 'states:StopExecution'],
-        resources: [stateMachineArn]
-    });
-};
-/**
- * Combine multiple policy statements into a policy document
- */
-const createPolicyDocument = (statements) => {
-    return new awsIam.PolicyDocument({
-        statements
-    });
-};
 
-/**
- * Environment-specific configuration management utilities
- */
 const RECAP_DEV_SSM_KEY = 'recap-dev-sync-endpoint';
 const recapDevEndpointCache = new WeakMap();
+const RECAP_DEV_TIMEOUT_WINDOW_SECONDS = 300;
 /**
- * Default configuration values by stage
- */
-const STAGE_DEFAULTS = {
-    dev: {
-        region: 'eu-west-1',
-        tags: {
-            Environment: 'development'
-        }
-    },
-    test: {
-        region: 'eu-west-1',
-        tags: {
-            Environment: 'test'
-        }
-    },
-    staging: {
-        region: 'eu-west-1',
-        tags: {
-            Environment: 'staging'
-        }
-    },
-    prod: {
-        region: 'eu-west-1',
-        tags: {
-            Environment: 'production'
-        }
-    }
-};
-/**
- * Get environment configuration with defaults
- */
-const getEnvironmentConfig = (stage, overrides) => {
-    const defaults = STAGE_DEFAULTS[stage];
-    return {
-        stage,
-        region: overrides?.region || defaults.region || 'eu-west-1',
-        account: overrides?.account || process.env.CDK_DEFAULT_ACCOUNT,
-        tags: {
-            ...defaults.tags,
-            ...overrides?.tags
-        }
-    };
-};
-/**
- * Get environment variable with stage prefix
- */
-const getStageEnvVar = (stage, key, defaultValue) => {
-    const stageKey = `${stage.toUpperCase()}_${key}`;
-    return process.env[stageKey] || process.env[key] || defaultValue;
-};
-/**
- * Get required environment variable
- */
-const getRequiredEnvVar = (key) => {
-    const value = process.env[key];
-    if (!value) {
-        throw new Error(`Required environment variable ${key} is not set`);
-    }
-    return value;
-};
-/**
- * Get environment variables for a Lambda function
- */
-const getLambdaEnvironmentVariables = (stage, additionalVars) => {
-    return {
-        STAGE: stage,
-        NODE_ENV: stage === 'prod' ? 'production' : 'development',
-        REGION: process.env.AWS_REGION || 'eu-west-1',
-        ...additionalVars
-    };
-};
-/**
- * Check if running in production stage
- */
-const isProduction = (stage) => {
-    return stage === 'prod';
-};
-/**
- * Check if running in development stage
- */
-const isDevelopment = (stage) => {
-    return stage === 'dev';
-};
-/**
- * Get stage from environment or default
+ * Returns the standard base environment variables injected into every Lambda.
+ * Centralised here so both EmLambdaFunction and LambdaWithQueue stay in sync.
  */
-const getStageFromEnv = (defaultStage = 'dev') => {
-    const stage = process.env.STAGE || process.env.CDK_STAGE || defaultStage;
-    if (!['dev', 'test', 'staging', 'prod'].includes(stage)) {
-        throw new Error(`Invalid stage: ${stage}. Must be one of: dev, test, staging, prod`);
-    }
-    return stage;
-};
-/**
- * Get stage-specific resource limits
- */
-const getResourceLimits = (stage) => {
-    switch (stage) {
-        case 'prod':
-            return {
-                lambdaMemory: 1024,
-                lambdaTimeout: 30,
-                apiThrottleRate: 10000,
-                apiThrottleBurst: 5000,
-                dynamoDbReadCapacity: 5,
-                dynamoDbWriteCapacity: 5,
-                logRetentionDays: 30
-            };
-        case 'staging':
-            return {
-                lambdaMemory: 1024,
-                lambdaTimeout: 30,
-                apiThrottleRate: 5000,
-                apiThrottleBurst: 2500,
-                dynamoDbReadCapacity: 3,
-                dynamoDbWriteCapacity: 3,
-                logRetentionDays: 14
-            };
-        case 'test':
-            return {
-                lambdaMemory: 512,
-                lambdaTimeout: 15,
-                apiThrottleRate: 1000,
-                apiThrottleBurst: 500,
-                dynamoDbReadCapacity: 1,
-                dynamoDbWriteCapacity: 1,
-                logRetentionDays: 7
-            };
-        case 'dev':
-            return {
-                lambdaMemory: 512,
-                lambdaTimeout: 15,
-                apiThrottleRate: 100,
-                apiThrottleBurst: 50,
-                dynamoDbReadCapacity: 1,
-                dynamoDbWriteCapacity: 1,
-                logRetentionDays: 3
-            };
-    }
-};
-const RECAP_DEV_TIMEOUT_WINDOW_SECONDS = 300;
+const buildBaseEnvironment = (stage, scope) => ({
+    STAGE: stage,
+    NODE_ENV: stage === 'prod' ? 'production' : 'development',
+    REGION: cdk.Stack.of(scope).region,
+});
 /**
  * Returns the env var block to inject for recap.dev, or an empty object.
- * Handles CDK dummy values returned by valueFromLookup when the SSM key is absent.
+ *
+ * The `dummy-value-` early-return guards against CDK's SSM lookup placeholder:
+ * `valueFromLookup` returns `dummy-value-…` strings during the first synth
+ * before the cache file is populated, and we must not bake those into the
+ * Lambda's environment.
  */
 const buildRecapDevEnvironment = (endpoint) => {
     if (!endpoint || endpoint.startsWith('dummy-value-')) {
         return {};
     }
+    let parsed;
     try {
-        const parsed = new URL(endpoint);
-        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
-            throw new Error(`recap.dev endpoint must use http or https, got: ${parsed.protocol}`);
-        }
+        parsed = new URL(endpoint);
+    }
+    catch {
+        throw new Error(`recap.dev endpoint is not a valid URL: "${endpoint}"`);
     }
-    catch (err) {
-        throw err instanceof Error
-            ? err
-            : new Error(`recap.dev endpoint is not a valid URL: ${endpoint}`);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`recap.dev endpoint must use http or https, got: ${parsed.protocol}`);
     }
     return {
         RECAP_DEV_SYNC_ENDPOINT: endpoint,
@@ -723,63 +446,90 @@ const buildRecapDevEnvironment = (endpoint) => {
  */
 const resolveRecapDevEndpoint = (scope) => {
     const stack = cdk.Stack.of(scope);
+    if (cdk.Token.isUnresolved(stack.account) || cdk.Token.isUnresolved(stack.region)) {
+        return undefined;
+    }
     if (!recapDevEndpointCache.has(stack)) {
         recapDevEndpointCache.set(stack, awsSsm.StringParameter.valueFromLookup(stack, RECAP_DEV_SSM_KEY));
     }
     return recapDevEndpointCache.get(stack);
 };
+
+const DEFAULT_LAMBDA_RUNTIME = awsLambda.Runtime.NODEJS_24_X;
+
+const DEFAULT_HANDLERS_DIR = 'src/handlers';
+const DEFAULT_OUT_DIR = 'dist/handlers';
 /**
- * Get stage-specific tracing configuration
+ * Resolve `handlerPath` into `codePath`, `handler`, and optionally `functionName`.
+ *
+ * Given `handlerPath: 'src/handlers/capture-screenshot/capture-screenshot-from-url'`:
+ * - `codePath` → `'dist/handlers/capture-screenshot/capture-screenshot-from-url'`
+ * - `handler` → `'index.handler'`
+ * - `functionName` → `'capture-screenshot-from-url'` (only when not explicitly provided)
+ *
+ * When `handlerPath` is not provided, `functionName` is required.
+ * `handler` and `codePath` may remain undefined if the caller has its own defaults.
  */
-const getTracingConfig = (stage) => {
+function resolveHandlerPath(config) {
+    const { handlerPath } = config;
+    if (handlerPath) {
+        const normalised = handlerPath.replace(/\.ts$/, '');
+        const startsWithHandlersDir = normalised.startsWith(DEFAULT_HANDLERS_DIR + '/');
+        const containsSeparator = normalised.includes('/') || normalised.includes(path__namespace.sep);
+        if (!startsWithHandlersDir && (path__namespace.isAbsolute(normalised) || containsSeparator)) {
+            // A bare basename like 'get-data' is fine (treated as relative to
+            // src/handlers). Anything with directory components must be rooted at
+            // DEFAULT_HANDLERS_DIR — otherwise we'd silently produce e.g.
+            // 'dist/handlers/src/lambdas/foo' and fail at synth with an opaque
+            // Code.fromAsset error far from the call site.
+            throw new Error(`resolveHandlerPath: handlerPath "${handlerPath}" must either be a bare basename or start with "${DEFAULT_HANDLERS_DIR}/".`);
+        }
+        const relative = startsWithHandlersDir
+            ? normalised.slice(DEFAULT_HANDLERS_DIR.length + 1)
+            : normalised;
+        return {
+            functionName: config.functionName ?? path__namespace.basename(relative),
+            handler: config.handler ?? 'index.handler',
+            codePath: config.codePath ?? path__namespace.join(DEFAULT_OUT_DIR, relative)
+        };
+    }
+    if (!config.functionName) {
+        throw new Error('Either `handlerPath` or `functionName` must be provided.');
+    }
     return {
-        enableXRay: stage === 'prod' || stage === 'staging',
-        enableLambdaInsights: stage === 'prod' || stage === 'staging',
-        enableActiveTracing: stage === 'prod'
+        functionName: config.functionName,
+        handler: config.handler,
+        codePath: config.codePath
     };
-};
-/**
- * Get stage-specific alarm thresholds
- */
-const getAlarmThresholds = (stage) => {
-    switch (stage) {
-        case 'prod':
-            return {
-                errorRate: 1,
-                throttleRate: 5,
-                durationP99: 5000,
-                concurrentExecutions: 900
-            };
-        case 'staging':
-            return {
-                errorRate: 5,
-                throttleRate: 10,
-                durationP99: 10000,
-                concurrentExecutions: 500
-            };
-        default:
-            return {
-                errorRate: 10,
-                throttleRate: 20,
-                durationP99: 15000,
-                concurrentExecutions: 100
-            };
-    }
-};
-
-const DEFAULT_LAMBDA_RUNTIME = awsLambda.Runtime.NODEJS_24_X;
+}
 
 class EmLambdaFunction extends constructs.Construct {
     constructor(scope, id, config) {
         super(scope, id);
-        const functionName = generateLambdaName(config.stage, config.serviceName, config.functionName);
+        const resolved = resolveHandlerPath(config);
+        const functionName = config.physicalName ??
+            generateLambdaName(config.stage, config.serviceName, resolved.functionName);
+        const extraPolicies = [];
+        if (config.vpcConfig) {
+            extraPolicies.push(awsIam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaVPCAccessExecutionRole'));
+        }
+        if (config.enableTracing) {
+            extraPolicies.push(awsIam.ManagedPolicy.fromAwsManagedPolicyName('AWSXRayDaemonWriteAccess'));
+        }
         const role = config.role ??
             createLambdaExecutionRole(this, 'Role', {
-                roleName: config.functionName,
+                roleName: resolved.functionName,
                 stage: config.stage,
                 serviceName: config.serviceName,
-                managedPolicies: config.vpcConfig ? ['AWSLambdaVPCAccessExecutionRole'] : undefined
+                managedPolicies: extraPolicies.length ? extraPolicies : undefined
             });
+        // When the caller supplies a role (typically EmStack's sharedRole during
+        // Serverless migration) createLambdaExecutionRole is bypassed and the
+        // VPC/X-Ray policies above are not attached. Attach them here so
+        // vpcConfig/enableTracing produce a working role regardless of source.
+        if (config.role) {
+            extraPolicies.forEach(policy => role.addManagedPolicy(policy));
+        }
         const logGroup = config.importExistingLogGroup
             ? awsLogs.LogGroup.fromLogGroupName(this, `${id}LogGroup`, `/aws/lambda/${functionName}`)
             : new awsLogs.LogGroup(this, `${id}LogGroup`, {
@@ -787,15 +537,20 @@ class EmLambdaFunction extends constructs.Construct {
                 retention: convertRetentionDays(config.logRetentionDays) ?? getLogRetentionDays(config.stage),
                 removalPolicy: getRemovalPolicy(config.stage)
             });
+        const handler = resolved.handler ?? config.handler;
+        const codePath = resolved.codePath ?? config.codePath;
+        if (!handler || !codePath) {
+            throw new Error(`EmLambdaFunction requires either \`handlerPath\` or both \`handler\` and \`codePath\` for "${resolved.functionName}".`);
+        }
         this.function = new awsLambda.Function(this, 'Function', {
             functionName,
             runtime: config.runtime ?? DEFAULT_LAMBDA_RUNTIME,
-            handler: config.handler,
-            code: awsLambda.Code.fromAsset(config.codePath),
+            handler,
+            code: awsLambda.Code.fromAsset(codePath),
             memorySize: config.memorySize ?? 1024,
             timeout: config.timeout ?? cdk.Duration.seconds(15),
             environment: {
-                ...getLambdaEnvironmentVariables(config.stage),
+                ...buildBaseEnvironment(config.stage, this),
                 ...(config.environment ?? {}),
                 ...buildRecapDevEnvironment(resolveRecapDevEndpoint(this))
             },
@@ -806,7 +561,7 @@ class EmLambdaFunction extends constructs.Construct {
             retryAttempts: config.retryAttempts,
             logGroup,
             layers: config.layers,
-            description: `${config.serviceName} - ${config.functionName}`,
+            description: `${config.serviceName} - ${resolved.functionName}`,
             ...(config.vpcConfig && {
                 vpc: config.vpcConfig.vpc,
                 vpcSubnets: config.vpcConfig.vpcSubnets,
@@ -1700,40 +1455,26 @@ const EVENT_PATTERNS = {
     })
 };
 
-const DEFAULT_HANDLERS_DIR = 'src/handlers';
-const DEFAULT_OUT_DIR = 'dist/handlers';
-/**
- * Resolve `handlerPath` into `codePath`, `handler`, and optionally `functionName`.
- *
- * Given `handlerPath: 'src/handlers/capture-screenshot/capture-screenshot-from-url'`:
- * - `codePath` → `'dist/handlers/capture-screenshot/capture-screenshot-from-url'`
- * - `handler` → `'index.handler'`
- * - `functionName` → `'capture-screenshot-from-url'` (only when not explicitly provided)
- *
- * When `handlerPath` is not provided, `functionName` is required.
- * `handler` and `codePath` may remain undefined if the caller has its own defaults.
- */
-function resolveHandlerPath(config) {
-    const { handlerPath } = config;
-    if (handlerPath) {
-        const normalised = handlerPath.replace(/\.ts$/, '');
-        const relative = normalised.startsWith(DEFAULT_HANDLERS_DIR + '/')
-            ? normalised.slice(DEFAULT_HANDLERS_DIR.length + 1)
-            : normalised;
-        return {
-            functionName: config.functionName ?? path.basename(relative),
-            handler: config.handler ?? 'index.handler',
-            codePath: config.codePath ?? path.join(DEFAULT_OUT_DIR, relative)
-        };
-    }
-    if (!config.functionName) {
-        throw new Error('Either `handlerPath` or `functionName` must be provided.');
+class DlqAlarm extends constructs.Construct {
+    constructor(scope, id, props) {
+        super(scope, id);
+        this.alarm = new awsCloudwatch.Alarm(this, 'Alarm', {
+            alarmName: props.alarmName,
+            metric: props.dlq.metricApproximateNumberOfMessagesVisible(),
+            threshold: 0,
+            comparisonOperator: awsCloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: 1,
+            treatMissingData: awsCloudwatch.TreatMissingData.NOT_BREACHING
+        });
+        this.alarm.addAlarmAction(new awsCloudwatchActions.SnsAction(props.alarmTopic));
+        if (props.alarmLogicalId) {
+            const cfnAlarm = this.alarm.node.defaultChild;
+            if (!(cfnAlarm instanceof awsCloudwatch.CfnAlarm)) {
+                throw new Error(`Cannot override alarm logical ID "${props.alarmLogicalId}": defaultChild is not a CfnAlarm.`);
+            }
+            cfnAlarm.overrideLogicalId(props.alarmLogicalId);
+        }
     }
-    return {
-        functionName: config.functionName,
-        handler: config.handler,
-        codePath: config.codePath
-    };
 }
 
 /**
@@ -1799,7 +1540,13 @@ const overrideLogGroupLogicalId = (logGroup, serverlessFunctionName) => {
  */
 const overrideFunctionLogicalIds = (fn, serverlessFunctionName) => {
     overrideLambdaLogicalId(fn, serverlessFunctionName);
-    overrideLogGroupLogicalId(fn.logGroup, serverlessFunctionName);
+    const logGroup = fn.logGroup;
+    if (!(logGroup instanceof constructs.Construct)) {
+        throw new Error(`Cannot override log group logical ID for "${serverlessFunctionName}": ` +
+            'fn.logGroup is not a Construct. ' +
+            'Imported log groups (importExistingLogGroup: true) cannot have their logical IDs overridden.');
+    }
+    overrideLogGroupLogicalId(logGroup, serverlessFunctionName);
 };
 /**
  * Override a Lambda layer's logical ID.
@@ -1826,39 +1573,250 @@ const overrideLayerLogicalId = (layer, logicalId) => {
  *
  * Only works with roles created in this stack, not imported roles.
  */
-const overrideRoleLogicalId = (role, logicalId = 'IamRoleLambdaExecution') => {
+const overrideRoleLogicalId = (role, logicalId = 'IamRoleLambdaExecution', options) => {
     const defaultChild = role.node.defaultChild;
     if (!(defaultChild instanceof awsIam.CfnRole)) {
         throw new Error('Cannot override role logical ID: the role does not have a CfnRole default child. ' +
             'Imported roles (e.g. via Role.fromRoleArn) cannot have their logical IDs overridden.');
     }
     defaultChild.overrideLogicalId(logicalId);
+    if (options?.roleName) {
+        defaultChild.addPropertyOverride('RoleName', options.roleName);
+    }
+    if (options?.deletePath) {
+        defaultChild.addPropertyDeletionOverride('Path');
+    }
 };
 /**
  * Create a CfnOutput with a Serverless Framework-compatible export name.
  * Export pattern: sls-{serviceName}-{stage}-{outputKey}
  */
-const createServerlessCompatibleOutput = (scope, id, props) => {
-    return new cdk.CfnOutput(scope, id, {
-        value: props.value,
-        description: props.description,
-        exportName: `sls-${props.serviceName}-${props.stage}-${props.outputKey}`
+const createServerlessCompatibleOutput = (scope, id, props) => new cdk.CfnOutput(scope, id, {
+    value: props.value,
+    description: props.description,
+    exportName: `sls-${props.serviceName}-${props.stage}-${props.outputKey}`
+});
+/**
+ * Creates an SQS queue with a dead-letter queue using the names and logical IDs
+ * from the existing Serverless stack.
+ *
+ * Use this during Serverless to CDK migrations when the queues already exist.
+ * The queue and DLQ logical IDs must match the CloudFormation resources created
+ * by Serverless, otherwise CloudFormation can replace the queues during deploy.
+ *
+ * Production queues are retained. Other stages use the shared removal policy
+ * from `getRemovalPolicy()`. The DLQ message retention is set to 14 days.
+ *
+ * @example
+ * ```typescript
+ * const alarmTopic = (scope as EmStack).alarmTopic()
+ * const { queue, dlq } = makeServerlessQueue(
+ *   scope, 'MqlEventsQueue', 'MqlEventsQueueDLQ',
+ *   `${svc}-mql-event-queue`, `${svc}-mql-event-queue-dlq`,
+ *   stage,
+ *   { alarm: { name: 'MqlEventsQueueDLQAlarm', topic: alarmTopic } },
+ * )
+ * ```
+ */
+function makeServerlessQueue(scope, queueLogicalId, dlqLogicalId, queueName, dlqName, stage, opts = {}) {
+    const removalPolicy = getRemovalPolicy(stage);
+    const dlq = new awsSqs.Queue(scope, dlqLogicalId, {
+        queueName: dlqName,
+        retentionPeriod: cdk.Duration.days(14),
+        removalPolicy
     });
-};
-
-class DlqAlarm extends constructs.Construct {
-    constructor(scope, id, props) {
-        super(scope, id);
-        this.alarm = new awsCloudwatch.Alarm(this, 'Alarm', {
-            alarmName: props.alarmName,
-            metric: props.dlq.metricApproximateNumberOfMessagesVisible(),
-            threshold: 0,
-            comparisonOperator: awsCloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD,
-            evaluationPeriods: 1,
-            treatMissingData: awsCloudwatch.TreatMissingData.NOT_BREACHING
+    const cfnDlq = dlq.node.defaultChild;
+    if (!(cfnDlq instanceof awsSqs.CfnQueue)) {
+        throw new Error(`Cannot override DLQ logical ID "${dlqLogicalId}": defaultChild is not a CfnQueue.`);
+    }
+    cfnDlq.overrideLogicalId(dlqLogicalId);
+    const queue = new awsSqs.Queue(scope, queueLogicalId, {
+        queueName,
+        visibilityTimeout: opts.visibilityTimeout ?? cdk.Duration.seconds(900),
+        deadLetterQueue: { queue: dlq, maxReceiveCount: opts.maxReceiveCount ?? 3 },
+        removalPolicy
+    });
+    const cfnQueue = queue.node.defaultChild;
+    if (!(cfnQueue instanceof awsSqs.CfnQueue)) {
+        throw new Error(`Cannot override queue logical ID "${queueLogicalId}": defaultChild is not a CfnQueue.`);
+    }
+    cfnQueue.overrideLogicalId(queueLogicalId);
+    if (opts.alarm) {
+        new DlqAlarm(scope, `${queueLogicalId}DLQAlarm`, {
+            dlq,
+            alarmName: opts.alarm.name,
+            alarmTopic: opts.alarm.topic,
+            alarmLogicalId: opts.alarm.logicalId
         });
-        this.alarm.addAlarmAction(new awsCloudwatchActions.SnsAction(props.alarmTopic));
     }
+    return { queue, dlq };
+}
+/**
+ * Creates an SNS to SQS subscription with the same logical ID as the existing
+ * Serverless resource.
+ *
+ * Use this when migrating an existing subscription from Serverless to CDK.
+ * `topic.addSubscription(new SqsSubscription(queue))` lets CDK generate the
+ * logical ID, which usually does not match the resource already in CloudFormation.
+ * That can cause the subscription to be replaced during deployment.
+ *
+ * Both the construct ID and CloudFormation logical ID are set from `logicalId`.
+ *
+ * **Queue policy not included.** Unlike CDK's `SqsSubscription`, this helper only
+ * creates the `AWS::SNS::Subscription`. It does NOT create an `AWS::SQS::QueuePolicy`
+ * allowing SNS to send to the queue. On migrated stacks the policy was already created
+ * by Serverless Framework — use `makeServerlessQueuePolicy` to preserve it with the
+ * correct logical ID. On new queues call `makeServerlessQueuePolicy` (or use the CDK
+ * `SqsSubscription` helper instead) to ensure SNS can deliver messages.
+ *
+ * @example
+ * ```typescript
+ * makeSnsToSqsSubscription(scope, 'TenantPurgeSubscription', {
+ *   topicArn: `arn:aws:sns:${region}:${accountId}:${stage}-emarketeer-event-purge-tenant-data`,
+ *   endpoint: queues.tenantPurgeQueue.queue.queueArn,
+ *   protocol: 'sqs',
+ *   rawMessageDelivery: true,
+ * })
+ * // Also preserve (or create) the matching queue policy:
+ * makeServerlessQueuePolicy(scope, 'TenantPurgeSQSPolicy', { ... })
+ * ```
+ */
+function makeSnsToSqsSubscription(scope, logicalId, props) {
+    const sub = new awsSns.CfnSubscription(scope, logicalId, props);
+    sub.overrideLogicalId(logicalId);
+    return sub;
+}
+/**
+ * Creates an SNS to Lambda subscription and matching invoke permission using
+ * logical IDs from the existing Serverless stack.
+ *
+ * Use this when migrating an existing SNS Lambda trigger to CDK. The normal CDK
+ * subscription helper generates its own logical IDs, so it can replace the
+ * Serverless-created subscription and permission during deploy. For SNS Lambda
+ * subscriptions that means events published during the replacement window are lost.
+ *
+ * Pass literal ARN strings for both the topic and Lambda function. Avoid using
+ * `topic.topicArn` or `function.functionArn` here, since changes in the generated
+ * CloudFormation expression can still force replacement even when the final ARN is
+ * the same.
+ *
+ * The Lambda function must have a fixed `physicalName`, otherwise the function ARN
+ * cannot be written safely by hand.
+ *
+ * Check the live CloudFormation stack for the subscription and permission logical
+ * IDs before using this helper:
+ *
+ * ```bash
+ * aws cloudformation list-stack-resources --stack-name <stack-name> \
+ *   --query "StackResourceSummaries[?ResourceType=='AWS::SNS::Subscription' ||
+ *            ResourceType=='AWS::Lambda::Permission'].[LogicalResourceId,ResourceType]" \
+ *   --output table
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const stagePrefix = stage.charAt(0).toUpperCase() + stage.slice(1)
+ * makeSnsToLambdaSubscription(
+ *   scope,
+ *   `HandleDashorderDashcreatedSnsSubscription${stagePrefix}myserviceeventordercreated`,
+ *   `HandleDashorderDashcreatedLambdaPermission${stagePrefix}myserviceeventordercreatedSNS`,
+ *   {
+ *     topicArn:    `arn:aws:sns:eu-west-1:${accountId}:${stage}-my-service-event-order-created`,
+ *     functionArn: `arn:aws:lambda:eu-west-1:${accountId}:function:my-service-${stage}-handle-order-created`,
+ *   }
+ * )
+ * ```
+ */
+function makeSnsToLambdaSubscription(scope, subscriptionLogicalId, permissionLogicalId, props) {
+    if (cdk.Token.isUnresolved(props.topicArn) || cdk.Token.isUnresolved(props.functionArn)) {
+        throw new Error('makeSnsToLambdaSubscription requires literal ARN strings, not CDK tokens. ' +
+            'Using topic.topicArn or function.functionArn produces a CloudFormation expression whose ' +
+            'rendered form can change independently of the resolved ARN, forcing subscription replacement. ' +
+            'Pass the physical ARN as a string literal (e.g. `arn:aws:sns:eu-west-1:${accountId}:${stage}-my-topic`).');
+    }
+    const subscription = new awsSns.CfnSubscription(scope, subscriptionLogicalId, {
+        topicArn: props.topicArn,
+        protocol: 'lambda',
+        endpoint: props.functionArn,
+    });
+    subscription.overrideLogicalId(subscriptionLogicalId);
+    const permission = new awsLambda.CfnPermission(scope, permissionLogicalId, {
+        action: 'lambda:InvokeFunction',
+        functionName: props.functionArn,
+        principal: 'sns.amazonaws.com',
+        sourceArn: props.topicArn,
+    });
+    permission.overrideLogicalId(permissionLogicalId);
+    subscription.addDependency(permission);
+    return { subscription, permission };
+}
+/**
+ * Creates an SQS queue policy using the logical ID from the existing Serverless
+ * stack.
+ *
+ * Use this for migrated queues instead of `queue.addToResourcePolicy()`. The CDK
+ * helper creates its own logical ID, which usually does not match the
+ * `AWS::SQS::QueuePolicy` resource already managed by CloudFormation.
+ *
+ * Both the construct ID and CloudFormation logical ID are set from `logicalId`.
+ *
+ * @example
+ * ```typescript
+ * makeServerlessQueuePolicy(scope, 'MqlEventSQSPolicy', {
+ *   queues: [queues.mqlEventsQueue.queue.queueUrl],
+ *   policyDocument: {
+ *     Version: '2012-10-17',
+ *     Statement: [{
+ *       Effect: 'Allow', Principal: '*', Action: 'sqs:SendMessage', Resource: '*',
+ *       // Keep the policy limited to the SNS topic that sends to this queue.
+ *       Condition: { ArnEquals: { 'aws:SourceArn': `arn:aws:sns:...` } },
+ *     }],
+ *   },
+ * })
+ * ```
+ */
+function makeServerlessQueuePolicy(scope, logicalId, props) {
+    const policy = new awsSqs.CfnQueuePolicy(scope, logicalId, props);
+    policy.overrideLogicalId(logicalId);
+    return policy;
+}
+/**
+ * Creates a DynamoDB table with the physical name and logical ID used by the
+ * existing Serverless stack.
+ *
+ * Use this when moving an existing Serverless-managed table to CDK. The logical
+ * ID should be copied from the CloudFormation resource, usually the resource key
+ * from `serverless.yml`. If it does not match, CloudFormation may replace the
+ * table during deploy.
+ *
+ * Defaults used by this helper:
+ * - billing mode is PAY_PER_REQUEST
+ * - point-in-time recovery is enabled only in prod
+ * - removal policy is RETAIN in prod and DESTROY in other stages
+ *
+ * @example
+ * ```typescript
+ * const table = makeServerlessDynamoTable(scope, 'LeadCountTable', `${stage}-em-my-service-lead-count`, stage, {
+ *   partitionKey: { name: 'streamId', type: AttributeType.STRING },
+ *   sortKey: { name: 'day', type: AttributeType.NUMBER },
+ * })
+ * ```
+ */
+function makeServerlessDynamoTable(scope, logicalId, tableName, stage, options) {
+    const table = new awsDynamodb.Table(scope, logicalId, {
+        tableName,
+        billingMode: awsDynamodb.BillingMode.PAY_PER_REQUEST,
+        pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: stage === 'prod' },
+        removalPolicy: getRemovalPolicy(stage),
+        ...options
+    });
+    const cfnTable = table.node.defaultChild;
+    if (!(cfnTable instanceof awsDynamodb.CfnTable)) {
+        throw new Error(`Cannot override DynamoDB table logical ID "${logicalId}": defaultChild is not a CfnTable. ` +
+            'Imported tables cannot have their logical IDs overridden.');
+    }
+    cfnTable.overrideLogicalId(logicalId);
+    return table;
 }
 
 class LambdaWithQueue extends constructs.Construct {
@@ -1867,7 +1825,7 @@ class LambdaWithQueue extends constructs.Construct {
         const resolved = resolveHandlerPath(props);
         const shortName = resolved.functionName;
         const resourceName = props.resourceName ?? shortName;
-        const functionName = generateLambdaName(props.stage, props.serviceName, shortName);
+        const functionName = props.physicalName ?? generateLambdaName(props.stage, props.serviceName, shortName);
         const handler = resolved.handler ?? props.handler ?? 'index.handler';
         const codePath = resolved.codePath ?? props.codePath ?? `./dist/handlers/${resourceName}`;
         if (props.reservedConcurrency === 0) {
@@ -1892,7 +1850,7 @@ class LambdaWithQueue extends constructs.Construct {
             },
             removalPolicy: getRemovalPolicy(props.stage)
         });
-        const role = props.role ?? this.createRole(props);
+        const role = props.role ?? this.createRole(props, enableTracing);
         const logGroup = new awsLogs.LogGroup(this, 'LogGroup', {
             logGroupName: `/aws/lambda/${functionName}`,
             retention: getLogRetentionDays(props.stage),
@@ -1907,6 +1865,7 @@ class LambdaWithQueue extends constructs.Construct {
             memorySize,
             timeout,
             environment: {
+                ...buildBaseEnvironment(props.stage, this),
                 ...(props.environment ?? {}),
                 ...buildRecapDevEnvironment(resolveRecapDevEndpoint(this))
             },
@@ -1944,7 +1903,8 @@ class LambdaWithQueue extends constructs.Construct {
         this.dlqAlarm = new DlqAlarm(this, 'DLQAlarm', {
             dlq: this.dlq,
             alarmName: props.alarmName ?? `${props.stage}-${props.serviceName}-${resourceName}-dlq-alarm`,
-            alarmTopic: props.alarmTopic
+            alarmTopic: props.alarmTopic,
+            alarmLogicalId: props.overrideLogicalIds?.alarm
         });
         additionalQueues.forEach(queue => {
             queue.grantSendMessages(this.function);
@@ -1968,15 +1928,8 @@ class LambdaWithQueue extends constructs.Construct {
             }
             cfnDlq.overrideLogicalId(props.overrideLogicalIds.dlq);
         }
-        if (props.overrideLogicalIds?.alarm) {
-            const cfnAlarm = this.dlqAlarm.alarm.node.defaultChild;
-            if (!(cfnAlarm instanceof awsCloudwatch.CfnAlarm)) {
-                throw new Error(`Cannot override alarm logical ID to "${props.overrideLogicalIds.alarm}": alarm does not have a CfnAlarm default child.`);
-            }
-            cfnAlarm.overrideLogicalId(props.overrideLogicalIds.alarm);
-        }
     }
-    createRole(props) {
+    createRole(props, enableTracing) {
         if (!props.roleName) {
             throw new Error('LambdaWithQueue requires either `role` or `roleName` to be provided.');
         }
@@ -1989,10 +1942,45 @@ class LambdaWithQueue extends constructs.Construct {
         if (props.vpcConfig) {
             role.addManagedPolicy(awsIam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaVPCAccessExecutionRole'));
         }
+        if (enableTracing) {
+            role.addManagedPolicy(awsIam.ManagedPolicy.fromAwsManagedPolicyName('AWSXRayDaemonWriteAccess'));
+        }
         return role;
     }
-    subscribeToTopic(topic, options) {
-        topic.addSubscription(new awsSnsSubscriptions.SqsSubscription(this.queue, options));
+    subscribeToTopic(topic, options, serverlessSubscriptionLogicalId) {
+        if (serverlessSubscriptionLogicalId !== undefined) {
+            const trimmed = serverlessSubscriptionLogicalId.trim();
+            if (!trimmed) {
+                throw new Error('subscribeToTopic: serverlessSubscriptionLogicalId must not be an empty string — ' +
+                    'omit the argument to use the standard CDK subscription path.');
+            }
+            if (options?.filterPolicy) {
+                throw new Error('subscribeToTopic: filterPolicy is not supported with serverlessSubscriptionLogicalId. ' +
+                    'Use the standard CDK subscription path instead.');
+            }
+            if (options?.filterPolicyWithMessageBody) {
+                throw new Error('subscribeToTopic: filterPolicyWithMessageBody is not supported with serverlessSubscriptionLogicalId. ' +
+                    'Use the standard CDK subscription path instead.');
+            }
+            if (options?.deadLetterQueue) {
+                throw new Error('subscribeToTopic: deadLetterQueue is not supported with serverlessSubscriptionLogicalId. ' +
+                    'Use the standard CDK subscription path instead.');
+            }
+            cdk.Annotations.of(this).addWarning(`subscribeToTopic with serverlessSubscriptionLogicalId="${trimmed}" ` +
+                'creates only the SNS subscription — no SQS queue policy is created. ' +
+                'On migrated stacks the queue policy already exists in CloudFormation; ' +
+                'preserve it with makeServerlessQueuePolicy(). ' +
+                'On new queues you must also call makeServerlessQueuePolicy() or SNS delivery will fail silently.');
+            makeSnsToSqsSubscription(this, trimmed, {
+                topicArn: topic.topicArn,
+                endpoint: this.queue.queueArn,
+                protocol: 'sqs',
+                rawMessageDelivery: options?.rawMessageDelivery
+            });
+        }
+        else {
+            topic.addSubscription(new awsSnsSubscriptions.SqsSubscription(this.queue, options));
+        }
     }
 }
 
@@ -2045,12 +2033,12 @@ class EmLambdaWithHttpApi extends constructs.Construct {
  */
 class TopicQueueConsumer extends LambdaWithQueue {
     constructor(scope, id, props) {
-        const { topic: topicOrArn, subscriptionOptions, ...queueProps } = props;
+        const { topic: topicOrArn, subscriptionOptions, serverlessSubscriptionLogicalId, ...queueProps } = props;
         super(scope, id, queueProps);
         const topic = typeof topicOrArn === 'string'
             ? awsSns.Topic.fromTopicArn(this, 'SubscribedTopic', topicOrArn)
             : topicOrArn;
-        this.subscribeToTopic(topic, subscriptionOptions);
+        this.subscribeToTopic(topic, subscriptionOptions, serverlessSubscriptionLogicalId);
     }
 }
 
@@ -2088,7 +2076,7 @@ class TopicQueueConsumer extends LambdaWithQueue {
  * }
  * ```
  */
-class EmStack extends cdk.Stack {
+class EmStack extends cdk__namespace.Stack {
     constructor(scope, id, props) {
         super(scope, id, {
             ...props,
@@ -2128,7 +2116,7 @@ class EmStack extends cdk.Stack {
     /**
      * Update default function config after construction.
      * Use this when defaults depend on resources created after `super()`.
-     * Environment is deep-merged with any existing defaults.
+     * The environment map is shallow-merged with existing defaults; all other keys are replaced.
      *
      * @example
      * ```typescript
@@ -2149,19 +2137,17 @@ class EmStack extends cdk.Stack {
             }
         };
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     mergeConfig(config) {
-        const defaults = this.defaultFunctionConfig;
-        const merged = { ...defaults, ...config };
         const defaultEnv = this.defaultFunctionConfig.environment;
         const configEnv = config.environment;
-        if (defaultEnv || configEnv) {
-            merged.environment = {
-                ...(defaultEnv ?? {}),
-                ...(configEnv ?? {})
-            };
-        }
-        return merged;
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        return {
+            ...this.defaultFunctionConfig,
+            ...config,
+            ...(defaultEnv || configEnv
+                ? { environment: { ...(defaultEnv ?? {}), ...(configEnv ?? {}) } }
+                : {})
+        };
     }
     /**
      * Create a Lambda function. Defaults `stage` and `serviceName` from the stack.
@@ -2169,8 +2155,11 @@ class EmStack extends cdk.Stack {
      * When `useSharedRole: true` (Serverless migration mode), also:
      * - Overrides Lambda logical ID to `{prefix}LambdaFunction`
      * - Overrides log group logical ID to `{prefix}LogGroup`
-     * - Sets log group removal policy to RETAIN
+     * - Sets log group removal policy via `getRemovalPolicy(stage)` (RETAIN in
+     *   prod, DESTROY otherwise — see utils/logs.ts)
      * - Uses the shared role unless `config.role` is provided
+     * - Throws if `importExistingLogGroup` is set — migration mode requires managed log groups
+     *   to override their logical IDs
      */
     createFunction(id, config) {
         const merged = this.mergeConfig(config);
@@ -2197,6 +2186,7 @@ class EmStack extends cdk.Stack {
             }
             overrideFunctionLogicalIds(fn.function, functionName);
         }
+        this.errorIfRoleOverrideInMigrationMode(fn, 'createFunction', functionName, merged.role);
         return fn;
     }
     /**
@@ -2222,7 +2212,7 @@ class EmStack extends cdk.Stack {
     createQueueConsumer(id, config) {
         const merged = this.mergeConfig(config);
         const { functionName } = resolveHandlerPath(merged);
-        return new LambdaWithQueue(this, id, {
+        const consumer = new LambdaWithQueue(this, id, {
             ...merged,
             stage: merged.stage ?? this.stage,
             serviceName: merged.serviceName ?? this.serviceName,
@@ -2231,6 +2221,8 @@ class EmStack extends cdk.Stack {
                 serverlessFunctionName: merged.serverlessFunctionName ?? functionName
             })
         });
+        this.errorIfRoleOverrideInMigrationMode(consumer, 'createQueueConsumer', functionName ?? id, merged.role);
+        return consumer;
     }
     /**
      * Create a Lambda function consuming messages from an SNS topic via SQS.
@@ -2252,20 +2244,23 @@ class EmStack extends cdk.Stack {
      * ```
      */
     createTopicQueueConsumer(id, config) {
-        const { topic, subscriptionOptions, ...queueConfig } = config;
+        const { topic, subscriptionOptions, serverlessSubscriptionLogicalId, ...queueConfig } = config;
         const merged = this.mergeConfig(queueConfig);
         const { functionName } = resolveHandlerPath(merged);
-        return new TopicQueueConsumer(this, id, {
+        const consumer = new TopicQueueConsumer(this, id, {
             ...merged,
             stage: merged.stage ?? this.stage,
             serviceName: merged.serviceName ?? this.serviceName,
             role: merged.role ?? this.sharedRole,
             topic,
             subscriptionOptions,
+            serverlessSubscriptionLogicalId,
             ...(this.sharedRole && {
                 serverlessFunctionName: merged.serverlessFunctionName ?? functionName
             })
         });
+        this.errorIfRoleOverrideInMigrationMode(consumer, 'createTopicQueueConsumer', functionName ?? id, merged.role);
+        return consumer;
     }
     /**
      * Create a scheduled Lambda function with an EventBridge rule.
@@ -2281,11 +2276,13 @@ class EmStack extends cdk.Stack {
      */
     createScheduledFunction(id, config) {
         const { schedule, ruleName, ruleDescription, ...functionConfig } = config;
-        const fn = this.createFunction(id, functionConfig);
+        const merged = this.mergeConfig(functionConfig);
+        const fn = this.createFunction(id, merged);
+        const { functionName } = resolveHandlerPath(merged);
         const rule = new EmEventBridgeRule(this, `${id}Rule`, {
-            stage: config.stage ?? this.stage,
-            serviceName: config.serviceName ?? this.serviceName,
-            ruleName: ruleName ?? resolveHandlerPath(functionConfig).functionName,
+            stage: functionConfig.stage ?? this.stage,
+            serviceName: functionConfig.serviceName ?? this.serviceName,
+            ruleName: ruleName ?? functionName,
             description: ruleDescription,
             schedule
         });
@@ -2316,35 +2313,51 @@ class EmStack extends cdk.Stack {
     /**
      * Import the alarm email topic by convention.
      * ARN: `arn:{partition}:sns:{region}:{account}:{stage}-alarm-email`
+     *
+     * Memoised: `Topic.fromTopicArn` registers a new construct on each call and
+     * CDK errors on duplicate construct IDs in the same scope, so multiple
+     * call sites would otherwise fail synth.
      */
     alarmTopic() {
-        const arn = `arn:${cdk.Aws.PARTITION}:sns:${cdk.Aws.REGION}:${cdk.Aws.ACCOUNT_ID}:${this.stage}-alarm-email`;
-        return awsSns.Topic.fromTopicArn(this, 'AlarmTopic', arn);
+        if (!this._alarmTopic) {
+            const arn = `arn:${cdk.Aws.PARTITION}:sns:${cdk.Aws.REGION}:${cdk.Aws.ACCOUNT_ID}:${this.stage}-alarm-email`;
+            this._alarmTopic = awsSns.Topic.fromTopicArn(this, 'AlarmTopic', arn);
+        }
+        return this._alarmTopic;
     }
     /**
      * Add a Lambda invoke policy to the shared role.
      * @param functionPattern - Optional function name pattern. Defaults to `{stage}-{serviceName}-*`.
      *   Pass `'*'` for account-wide access.
+     *
+     * **Note:** The default pattern only matches functions named with the CDK convention
+     * (`{stage}-{serviceName}-{fn}`). Functions created with `physicalName` using the legacy
+     * Serverless convention (`{service}-{stage}-{fn}`) will not be matched. Pass `'*'` when
+     * the service has any `physicalName` functions that must be invocable.
      */
     addLambdaInvokePolicy(functionPattern) {
-        this.requireSharedRole('addLambdaInvokePolicy');
+        if (functionPattern !== undefined && functionPattern.trim() === '') {
+            throw new Error('addLambdaInvokePolicy: functionPattern must not be empty.');
+        }
+        const role = this.requireSharedRole('addLambdaInvokePolicy');
         const pattern = functionPattern ?? `${this.stage}-${this.serviceName}-*`;
-        this.sharedRole.addToPolicy(new awsIam.PolicyStatement({
+        const resources = pattern === '*'
+            ? ['*']
+            : [`arn:${cdk.Aws.PARTITION}:lambda:${cdk.Aws.REGION}:${cdk.Aws.ACCOUNT_ID}:function:${pattern}`];
+        role.addToPolicy(new awsIam.PolicyStatement({
             effect: awsIam.Effect.ALLOW,
             actions: ['lambda:InvokeFunction'],
-            resources: [
-                `arn:${cdk.Aws.PARTITION}:lambda:${cdk.Aws.REGION}:${cdk.Aws.ACCOUNT_ID}:function:${pattern}`
-            ]
+            resources
         }));
     }
     /**
      * Add a Kinesis PutRecord/PutRecords policy to the shared role.
-     * @param streamName - Short stream name (prefixed with `{stage}-`).
+     * @param streamOrName - An IStream reference, or a short stream name (prefixed with `{stage}-`).
      */
-    addKinesisPolicy(streamName) {
-        this.requireSharedRole('addKinesisPolicy');
-        const arn = `arn:${cdk.Aws.PARTITION}:kinesis:${cdk.Aws.REGION}:${cdk.Aws.ACCOUNT_ID}:stream/${this.stage}-${streamName}`;
-        this.sharedRole.addToPolicy(new awsIam.PolicyStatement({
+    addKinesisPolicy(streamOrName) {
+        const role = this.requireSharedRole('addKinesisPolicy');
+        const arn = this.resolveResourceArn(streamOrName, 'addKinesisPolicy', 'streamName', name => `arn:${cdk.Aws.PARTITION}:kinesis:${cdk.Aws.REGION}:${cdk.Aws.ACCOUNT_ID}:stream/${this.stage}-${name}`, stream => stream.streamArn);
+        role.addToPolicy(new awsIam.PolicyStatement({
             effect: awsIam.Effect.ALLOW,
             actions: ['kinesis:PutRecord', 'kinesis:PutRecords'],
             resources: [arn]
@@ -2355,11 +2368,9 @@ class EmStack extends cdk.Stack {
      * @param topicOrName - An ITopic reference, or a short topic name (prefixed with `{stage}-`).
      */
     addSnsPublishPolicy(topicOrName) {
-        this.requireSharedRole('addSnsPublishPolicy');
-        const arn = typeof topicOrName === 'string'
-            ? `arn:${cdk.Aws.PARTITION}:sns:${cdk.Aws.REGION}:${cdk.Aws.ACCOUNT_ID}:${this.stage}-${topicOrName}`
-            : topicOrName.topicArn;
-        this.sharedRole.addToPolicy(new awsIam.PolicyStatement({
+        const role = this.requireSharedRole('addSnsPublishPolicy');
+        const arn = this.resolveResourceArn(topicOrName, 'addSnsPublishPolicy', 'topicName', name => `arn:${cdk.Aws.PARTITION}:sns:${cdk.Aws.REGION}:${cdk.Aws.ACCOUNT_ID}:${this.stage}-${name}`, topic => topic.topicArn);
+        role.addToPolicy(new awsIam.PolicyStatement({
             effect: awsIam.Effect.ALLOW,
             actions: ['sns:Publish'],
             resources: [arn]
@@ -2367,21 +2378,220 @@ class EmStack extends cdk.Stack {
     }
     /**
      * Add an SQS SendMessage policy to the shared role.
-     * @param queueName - Short queue name (prefixed with `{stage}-`).
+     * @param queueOrNames - One or more IQueue references and/or short queue names
+     *   (string names are prefixed with `{stage}-`).
      */
-    addSqsSendPolicy(queueName) {
-        this.requireSharedRole('addSqsSendPolicy');
-        const arn = `arn:${cdk.Aws.PARTITION}:sqs:${cdk.Aws.REGION}:${cdk.Aws.ACCOUNT_ID}:${this.stage}-${queueName}`;
-        this.sharedRole.addToPolicy(new awsIam.PolicyStatement({
+    addSqsSendPolicy(queueOrNames) {
+        const items = Array.isArray(queueOrNames) ? queueOrNames : [queueOrNames];
+        if (items.length === 0) {
+            throw new Error('addSqsSendPolicy: queueOrNames must not be empty.');
+        }
+        const role = this.requireSharedRole('addSqsSendPolicy');
+        const resources = items.map(item => this.resolveResourceArn(item, 'addSqsSendPolicy', 'queueName', name => `arn:${cdk.Aws.PARTITION}:sqs:${cdk.Aws.REGION}:${cdk.Aws.ACCOUNT_ID}:${this.stage}-${name}`, queue => queue.queueArn));
+        role.addToPolicy(new awsIam.PolicyStatement({
             effect: awsIam.Effect.ALLOW,
             actions: ['sqs:SendMessage', 'sqs:GetQueueAttributes', 'sqs:GetQueueUrl'],
-            resources: [arn]
+            resources
+        }));
+    }
+    /** Add an XRay tracing policy to the shared role. */
+    addXRayPolicy() {
+        const role = this.requireSharedRole('addXRayPolicy');
+        role.addToPolicy(createXRayTracingPolicy());
+    }
+    /**
+     * Add a CloudWatch Logs policy to the shared role.
+     * Grants create, write, describe, read, and query access on all log groups.
+     */
+    addCloudWatchLogsPolicy() {
+        const role = this.requireSharedRole('addCloudWatchLogsPolicy');
+        role.addToPolicy(new awsIam.PolicyStatement({
+            effect: awsIam.Effect.ALLOW,
+            actions: [
+                'logs:CreateLogGroup',
+                'logs:CreateLogStream',
+                'logs:PutLogEvents',
+                'logs:DescribeLogGroups',
+                'logs:DescribeLogStreams',
+                'logs:FilterLogEvents',
+                'logs:GetLogEvents',
+                'logs:StartQuery',
+                'logs:StopQuery',
+                'logs:GetQueryResults'
+            ],
+            resources: ['*']
+        }));
+    }
+    /**
+     * Add an SNS policy to the shared role.
+     * @param options.actions - SNS actions (e.g. ['sns:Publish', 'sns:Subscribe']).
+     * @param options.resources - Resource ARNs. When omitted, defaults to `['*']`
+     *   (account-wide access). Prefer `addSnsPublishPolicy(topicArn)` for scoped
+     *   publish-only access to a specific topic.
+     */
+    addSnsPolicy(options) {
+        if (options.actions.length === 0) {
+            throw new Error('addSnsPolicy: actions must not be empty.');
+        }
+        if (options.resources && options.resources.length === 0) {
+            throw new Error('addSnsPolicy: resources must not be empty. Omit the field to grant account-wide access explicitly.');
+        }
+        const role = this.requireSharedRole('addSnsPolicy');
+        if (!options.resources) {
+            cdk.Annotations.of(this).addWarning('addSnsPolicy: no resources specified — policy grants account-wide SNS access on all topics. ' +
+                'Pass resources to scope the policy, or use addSnsPublishPolicy(topicArn) for publish access.');
+        }
+        role.addToPolicy(new awsIam.PolicyStatement({
+            effect: awsIam.Effect.ALLOW,
+            actions: options.actions,
+            resources: options.resources ?? ['*']
+        }));
+    }
+    /**
+     * Add an SQS consumer policy to the shared role.
+     * Grants ChangeMessageVisibility, DeleteMessage, ReceiveMessage, and GetQueueAttributes on each queue.
+     * Use `addSqsSendPolicy` separately for queues the service also produces to.
+     * @param queues - One or more IQueue references and/or short queue names
+     *   (string names are prefixed with `{stage}-`).
+     */
+    addSqsConsumerPolicy(queues) {
+        if (queues.length === 0) {
+            throw new Error('addSqsConsumerPolicy: queues must not be empty.');
+        }
+        const role = this.requireSharedRole('addSqsConsumerPolicy');
+        const resources = queues.map(item => this.resolveResourceArn(item, 'addSqsConsumerPolicy', 'queueName', name => `arn:${cdk.Aws.PARTITION}:sqs:${cdk.Aws.REGION}:${cdk.Aws.ACCOUNT_ID}:${this.stage}-${name}`, queue => queue.queueArn));
+        role.addToPolicy(new awsIam.PolicyStatement({
+            effect: awsIam.Effect.ALLOW,
+            actions: [
+                'sqs:ChangeMessageVisibility',
+                'sqs:DeleteMessage',
+                'sqs:ReceiveMessage',
+                'sqs:GetQueueAttributes'
+            ],
+            resources
+        }));
+    }
+    /**
+     * Add an execute-api:Invoke policy to the shared role.
+     * Resources are scoped to `*` — API Gateway requires the full execution ARN
+     * (`arn:{partition}:execute-api:{region}:{account}:{api-id}/{stage}/{method}/{path}`)
+     * which is not available as a stable value in migration stacks.
+     */
+    addExecuteApiPolicy() {
+        const role = this.requireSharedRole('addExecuteApiPolicy');
+        role.addToPolicy(new awsIam.PolicyStatement({
+            effect: awsIam.Effect.ALLOW,
+            actions: ['execute-api:Invoke'],
+            resources: ['*']
         }));
     }
+    /**
+     * Add an S3 policy to the shared role.
+     * @param bucketOrName - An IBucket reference, or a full bucket name (no stage prefix added).
+     * @param actions - S3 actions to grant. Defaults to `['s3:GetObject', 's3:PutObject',
+     *   's3:DeleteObject', 's3:ListBucket']`. Pass an explicit non-empty list for narrower or broader access.
+     */
+    addS3Policy(bucketOrName, actions) {
+        if (actions && actions.length === 0) {
+            throw new Error('addS3Policy: actions must not be empty.');
+        }
+        const role = this.requireSharedRole('addS3Policy');
+        const bucketArn = this.resolveResourceArn(bucketOrName, 'addS3Policy', 'bucketName', name => `arn:${cdk.Aws.PARTITION}:s3:::${name}`, bucket => bucket.bucketArn);
+        role.addToPolicy(new awsIam.PolicyStatement({
+            effect: awsIam.Effect.ALLOW,
+            actions: actions ?? ['s3:GetObject', 's3:PutObject', 's3:DeleteObject', 's3:ListBucket'],
+            resources: [bucketArn, `${bucketArn}/*`]
+        }));
+    }
+    /**
+     * Add a DynamoDB policy to the shared role.
+     * Grants read, write, transact, and describe actions on each table.
+     *
+     * String-name ARNs use literal `*` for region and account. This matches the
+     * Serverless Framework's source policy on migrated stacks; replacing the `*`
+     * with `${Aws.REGION}/${Aws.ACCOUNT_ID}` would generate a noisy CloudFormation
+     * diff on first deploy without changing effective access.
+     *
+     * @param tables - One or more ITable references and/or short table names
+     *   (string names are prefixed with `{stage}-`).
+     * @param options.streamTables - Tables to also grant stream read access.
+     *   Accepts ITable refs (uses tableStreamArn) or string short names.
+     * @param options.indexTables - Tables to also grant Query/Scan on all indexes.
+     *   Uses a separate policy statement scoped to only dynamodb:Query and dynamodb:Scan.
+     */
+    addDynamoDbPolicy(tables, options) {
+        if (tables.length === 0) {
+            throw new Error('addDynamoDbPolicy: tables must not be empty.');
+        }
+        const role = this.requireSharedRole('addDynamoDbPolicy');
+        const tableArns = tables.map(item => this.resolveResourceArn(item, 'addDynamoDbPolicy', 'tableName', name => `arn:${cdk.Aws.PARTITION}:dynamodb:*:*:table/${this.stage}-${name}`, table => table.tableArn));
+        const streamArns = (options?.streamTables ?? []).map(item => this.resolveResourceArn(item, 'addDynamoDbPolicy(streamTables)', 'tableName', name => `arn:${cdk.Aws.PARTITION}:dynamodb:*:*:table/${this.stage}-${name}/stream/*`, table => table.tableStreamArn ?? `${table.tableArn}/stream/*`));
+        role.addToPolicy(new awsIam.PolicyStatement({
+            effect: awsIam.Effect.ALLOW,
+            actions: [
+                'dynamodb:GetItem',
+                'dynamodb:PutItem',
+                'dynamodb:UpdateItem',
+                'dynamodb:DeleteItem',
+                'dynamodb:Query',
+                'dynamodb:Scan',
+                'dynamodb:BatchGetItem',
+                'dynamodb:BatchWriteItem',
+                'dynamodb:TransactGetItems',
+                'dynamodb:TransactWriteItems',
+                'dynamodb:DescribeTable',
+                'dynamodb:DescribeStream',
+                'dynamodb:GetRecords',
+                'dynamodb:GetShardIterator',
+                'dynamodb:ListStreams'
+            ],
+            resources: [...tableArns, ...streamArns]
+        }));
+        const indexArns = (options?.indexTables ?? []).map(item => this.resolveResourceArn(item, 'addDynamoDbPolicy(indexTables)', 'tableName', name => `arn:${cdk.Aws.PARTITION}:dynamodb:*:*:table/${this.stage}-${name}/index/*`, table => `${table.tableArn}/index/*`));
+        if (indexArns.length > 0) {
+            role.addToPolicy(new awsIam.PolicyStatement({
+                effect: awsIam.Effect.ALLOW,
+                actions: ['dynamodb:Query', 'dynamodb:Scan'],
+                resources: indexArns,
+            }));
+        }
+    }
     requireSharedRole(methodName) {
         if (!this.sharedRole) {
             throw new Error(`${methodName}() requires useSharedRole: true on the stack.`);
         }
+        return this.sharedRole;
+    }
+    /**
+     * Resolve a CDK resource reference or short name into an ARN string.
+     * Centralises empty-input validation so callers (add*Policy methods)
+     * fail loud at synth instead of producing a malformed ARN that
+     * CloudFormation later rejects with a generic error.
+     */
+    resolveResourceArn(refOrName, methodName, nameLabel, fromName, fromRef) {
+        if (typeof refOrName === 'string') {
+            if (refOrName.trim() === '') {
+                throw new Error(`${methodName}: ${nameLabel} must not be empty.`);
+            }
+            return fromName(refOrName);
+        }
+        return fromRef(refOrName);
+    }
+    /**
+     * Blocks synth with an error when a custom role is passed in migration mode.
+     * The Lambda logical ID is overridden to match Serverless naming, but the
+     * custom role's logical ID will NOT be pinned — CloudFormation may replace it.
+     * Uses addError (not addWarning) so the misconfiguration is caught before a
+     * changeset is created.
+     * Called from createFunction, createQueueConsumer, and createTopicQueueConsumer.
+     */
+    errorIfRoleOverrideInMigrationMode(scope, callerMethod, functionName, role) {
+        if (this.sharedRole && role && role !== this.sharedRole) {
+            cdk.Annotations.of(scope).addError(`${callerMethod}("${functionName}"): a custom role was provided in migration mode (useSharedRole: true). ` +
+                'The Lambda logical ID will be overridden to match Serverless naming, but the custom role\'s logical ID ' +
+                'will NOT be pinned to IamRoleLambdaExecution — CloudFormation may replace the role on deploy. ' +
+                'Pass the shared role via the stack\'s sharedRole property instead, or omit config.role.');
+        }
     }
     /**
      * Create a CfnOutput with a stable export name.
@@ -2403,31 +2613,36 @@ class EmStack extends cdk.Stack {
 }
 
 function createRdsVpcConfig(scope, stage, config) {
-    const vpc = ec2.Vpc.fromLookup(scope, `RdsVpc-${stage}`, {
+    const vpc = ec2__namespace.Vpc.fromLookup(scope, `RdsVpc-${stage}`, {
         vpcId: config.vpcId
     });
     // The imported subnets are only handed to Lambda's VpcConfig. We never read
     // `subnet.routeTable.routeTableId`, so acknowledge the CDK warning that
     // `fromSubnetId` emits for imports without route-table metadata.
     const privateSubnets = config.privateSubnetIds.map((subnetId, index) => {
-        const subnet = ec2.Subnet.fromSubnetId(scope, `RdsPrivateSubnet${index}-${stage}`, subnetId);
+        const subnet = ec2__namespace.Subnet.fromSubnetId(scope, `RdsPrivateSubnet${index}-${stage}`, subnetId);
         cdk.Annotations.of(subnet).acknowledgeWarning('@aws-cdk/aws-ec2:noSubnetRouteTableId', 'This construct only passes imported subnets to Lambda VpcConfig and does not require routeTableId metadata.');
         return subnet;
     });
-    const lambdaSecurityGroup = new ec2.SecurityGroup(scope, `RdsLambdaSecurityGroup-${stage}`, {
+    const lambdaSecurityGroup = new ec2__namespace.SecurityGroup(scope, `RdsLambdaSecurityGroup-${stage}`, {
         vpc,
         description: config.securityGroupDescription ?? 'Lambda security group for RDS access',
         allowAllOutbound: true
     });
-    if (config.overrideLogicalIds?.securityGroup) {
+    if (config.overrideLogicalIds?.securityGroup || config.manageSgEgress === false) {
         const cfnSg = lambdaSecurityGroup.node.defaultChild;
-        if (!(cfnSg instanceof ec2.CfnSecurityGroup)) {
-            throw new Error(`Cannot override security group logical ID to "${config.overrideLogicalIds.securityGroup}": ` +
-                'security group does not have a CfnSecurityGroup default child.');
+        if (!(cfnSg instanceof ec2__namespace.CfnSecurityGroup)) {
+            throw new Error('Security group does not have a CfnSecurityGroup default child — ' +
+                'cannot apply overrideLogicalIds.securityGroup or manageSgEgress.');
+        }
+        if (config.overrideLogicalIds?.securityGroup) {
+            cfnSg.overrideLogicalId(config.overrideLogicalIds.securityGroup);
+        }
+        if (config.manageSgEgress === false) {
+            cfnSg.addPropertyDeletionOverride('SecurityGroupEgress');
         }
-        cfnSg.overrideLogicalId(config.overrideLogicalIds.securityGroup);
     }
-    const ingress = new ec2.CfnSecurityGroupIngress(scope, `RdsIngress-${stage}`, {
+    const ingress = new ec2__namespace.CfnSecurityGroupIngress(scope, `RdsIngress-${stage}`, {
         groupId: config.dbSecurityGroupId,
         ipProtocol: 'tcp',
         fromPort: config.dbPort ?? 3306,
@@ -2438,6 +2653,15 @@ function createRdsVpcConfig(scope, stage, config) {
     if (config.overrideLogicalIds?.ingress) {
         ingress.overrideLogicalId(config.overrideLogicalIds.ingress);
     }
+    if (config.overrideLogicalIds?.securityGroup) {
+        // When the SG logical ID is pinned, CDK's auto-generated `Ref` on the
+        // ingress points at the original (CDK-generated) logical ID. CloudFormation
+        // can't resolve that reference at deploy and the changeset fails. Rewrite
+        // the Ref to the overridden ID.
+        ingress.addPropertyOverride('SourceSecurityGroupId', {
+            Ref: config.overrideLogicalIds.securityGroup
+        });
+    }
     if (config.sharedRole) {
         config.sharedRole.addManagedPolicy(awsIam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaVPCAccessExecutionRole'));
     }
@@ -2462,7 +2686,7 @@ function createRdsVpcConfig(scope, stage, config) {
  * ```
  */
 const createEmApp = (options) => {
-    const app = new cdk.App({
+    const app = new cdk__namespace.App({
         context: {
             ...cxApi.CURRENTLY_RECOMMENDED_FLAGS,
             ...options?.context
@@ -2508,7 +2732,7 @@ function getAccountRdsVpcConfig(stage) {
                 dbSecurityGroupId: 'sg-427bda39'
             };
         default:
-            throw new Error(`Unsupported RDS VPC stage: ${stage}. Only 'dev' and 'prod' are supported.`);
+            throw new Error(`getAccountRdsVpcConfig: unsupported stage "${stage}". Only 'dev' and 'prod' are supported.`);
     }
 }
 
@@ -2531,41 +2755,26 @@ exports.ServiceLambdaWithQueue = ServiceLambdaWithQueue;
 exports.TopicQueueConsumer = TopicQueueConsumer;
 exports.applyStandardTags = applyStandardTags;
 exports.applyTags = applyTags;
+exports.buildBaseEnvironment = buildBaseEnvironment;
 exports.buildRecapDevEnvironment = buildRecapDevEnvironment;
 exports.convertRetentionDays = convertRetentionDays;
 exports.createApiGatewayLogGroup = createApiGatewayLogGroup;
-exports.createCloudWatchLogsPolicy = createCloudWatchLogsPolicy;
-exports.createDynamoDBAccessPolicy = createDynamoDBAccessPolicy;
-exports.createDynamoDBReadPolicy = createDynamoDBReadPolicy;
-exports.createDynamoDBWritePolicy = createDynamoDBWritePolicy;
 exports.createEmApp = createEmApp;
-exports.createEventBridgePutEventsPolicy = createEventBridgePutEventsPolicy;
 exports.createEventBridgeRule = createEventBridgeRule;
 exports.createEventPatternRule = createEventPatternRule;
 exports.createFifoQueue = createFifoQueue;
 exports.createFifoTopic = createFifoTopic;
 exports.createHttpApi = createHttpApi;
-exports.createKMSDecryptPolicy = createKMSDecryptPolicy;
 exports.createKeyValueTable = createKeyValueTable;
 exports.createLambdaExecutionRole = createLambdaExecutionRole;
-exports.createLambdaInvokePolicy = createLambdaInvokePolicy;
-exports.createLambdaLogGroup = createLambdaLogGroup;
 exports.createLogGroup = createLogGroup;
-exports.createPolicyDocument = createPolicyDocument;
 exports.createQueue = createQueue;
 exports.createQueueWithDLQ = createQueueWithDLQ;
 exports.createRdsVpcConfig = createRdsVpcConfig;
 exports.createRestApi = createRestApi;
-exports.createS3AccessPolicy = createS3AccessPolicy;
-exports.createS3ReadPolicy = createS3ReadPolicy;
-exports.createSNSPublishPolicy = createSNSPublishPolicy;
-exports.createSQSAccessPolicy = createSQSAccessPolicy;
-exports.createSSMParameterPolicy = createSSMParameterPolicy;
 exports.createScheduledRule = createScheduledRule;
-exports.createSecretsManagerPolicy = createSecretsManagerPolicy;
 exports.createServerlessCompatibleOutput = createServerlessCompatibleOutput;
 exports.createSingleTable = createSingleTable;
-exports.createStepFunctionsExecutionPolicy = createStepFunctionsExecutionPolicy;
 exports.createTopic = createTopic;
 exports.createXRayTracingPolicy = createXRayTracingPolicy;
 exports.generateApiName = generateApiName;
@@ -2580,29 +2789,23 @@ exports.generateStandardTags = generateStandardTags;
 exports.generateTableName = generateTableName;
 exports.generateTopicName = generateTopicName;
 exports.getAccountRdsVpcConfig = getAccountRdsVpcConfig;
-exports.getAlarmThresholds = getAlarmThresholds;
 exports.getComplianceTags = getComplianceTags;
 exports.getCostAllocationTags = getCostAllocationTags;
-exports.getEnvironmentConfig = getEnvironmentConfig;
 exports.getEnvironmentTags = getEnvironmentTags;
-exports.getLambdaEnvironmentVariables = getLambdaEnvironmentVariables;
 exports.getLogRetentionDays = getLogRetentionDays;
 exports.getRemovalPolicy = getRemovalPolicy;
-exports.getRequiredEnvVar = getRequiredEnvVar;
-exports.getResourceLimits = getResourceLimits;
-exports.getStageEnvVar = getStageEnvVar;
-exports.getStageFromEnv = getStageFromEnv;
-exports.getTracingConfig = getTracingConfig;
-exports.isDevelopment = isDevelopment;
-exports.isProduction = isProduction;
 exports.isValidStage = isValidStage;
+exports.makeServerlessDynamoTable = makeServerlessDynamoTable;
+exports.makeServerlessQueue = makeServerlessQueue;
+exports.makeServerlessQueuePolicy = makeServerlessQueuePolicy;
+exports.makeSnsToLambdaSubscription = makeSnsToLambdaSubscription;
+exports.makeSnsToSqsSubscription = makeSnsToSqsSubscription;
 exports.mergeTags = mergeTags;
 exports.overrideFunctionLogicalIds = overrideFunctionLogicalIds;
 exports.overrideLayerLogicalId = overrideLayerLogicalId;
 exports.overrideRoleLogicalId = overrideRoleLogicalId;
 exports.resolveHandlerPath = resolveHandlerPath;
 exports.resolveRecapDevEndpoint = resolveRecapDevEndpoint;
-exports.shouldEnableLogInsights = shouldEnableLogInsights;
 exports.stageToUpperCase = stageToUpperCase;
 exports.toServerlessLogicalIdPrefix = toServerlessLogicalIdPrefix;
 //# sourceMappingURL=index.js.map