@fjall/components-infrastructure 0.96.0 → 0.99.1

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

@@ -6,9 +6,8 @@ import { fileURLToPath } from "node:url";
 import { SqsEventSource, DynamoEventSource, S3EventSource } from "aws-cdk-lib/aws-lambda-event-sources";
 import { EventType } from "aws-cdk-lib/aws-s3";
 import { PolicyStatement, Effect } from "aws-cdk-lib/aws-iam";
-import { Rule, Schedule } from "aws-cdk-lib/aws-events";
-import { LambdaFunction as LambdaTarget } from "aws-cdk-lib/aws-events-targets";
-import { LogGroup, RetentionDays } from "aws-cdk-lib/aws-logs";
+import { RetentionDays } from "aws-cdk-lib/aws-logs";
+import { LogGroup } from "../logging/logGroup.js";
 import { Secret } from "aws-cdk-lib/aws-secretsmanager";
 import { v4 as uuid } from "uuid";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -20,6 +19,18 @@ function addPoliciesToRole(target, statements) {
         target.addToRolePolicy(statement);
     }
 }
+/**
+ * CDK's auto-generated Lambda execution role does not accept a description
+ * through FunctionProps; reach for the L1 CfnRole and set it directly so
+ * SOC2 audits see a meaningful purpose on every role.
+ */
+function applyRoleDescription(fn, description) {
+    if (description === undefined)
+        return;
+    const cfnRole = fn.role?.node.defaultChild;
+    if (cfnRole !== undefined)
+        cfnRole.description = description;
+}
 /**
  * AWS Parameters and Secrets Lambda Extension configuration.
  * @see https://docs.aws.amazon.com/systems-manager/latest/userguide/ps-integration-lambda-extensions.html
@@ -30,19 +41,26 @@ const SECRETS_EXTENSION = {
     /** Cache TTL in seconds - 60s supports secret rotation while reducing API calls */
     CACHE_TTL_SECONDS: "60"
 };
+/**
+ * Default Lambda timeout in seconds. Coupled across the singleton constructor,
+ * the standard constructor, and the alarm wiring — drift would silently
+ * mis-tune alarms relative to runtime behaviour.
+ */
+const LAMBDA_DEFAULT_TIMEOUT_SECONDS = 300;
 export class SingletonFunction extends singletonFunction {
     constructor(scope, id, props) {
         super(scope, id, {
             ...props,
             uuid: props.uuid ?? uuid(),
-            timeout: Duration.seconds(300),
-            description: props.lambdaDescription || `${id} singleton lambda`,
+            timeout: Duration.seconds(props.timeout ?? LAMBDA_DEFAULT_TIMEOUT_SECONDS),
+            description: props.lambdaDescription ?? `${id} singleton lambda`,
             runtime: props.runtime,
             ephemeralStorageSize: props.ephemeralStorageSize
                 ? Size.mebibytes(props.ephemeralStorageSize)
                 : undefined
         });
         addPoliciesToRole(this, props.inlinePolicy);
+        applyRoleDescription(this, props.roleDescription);
     }
     /**
      * The Lambda's execution role (auto-generated by CDK)
@@ -60,26 +78,25 @@ export class LambdaFunction extends Function {
         super(scope, id, {
             ...props,
             vpcSubnets,
-            timeout: props.timeout
-                ? Duration.seconds(props.timeout)
-                : Duration.seconds(300),
-            memorySize: props.memorySize || 128,
+            timeout: Duration.seconds(props.timeout ?? LAMBDA_DEFAULT_TIMEOUT_SECONDS),
+            memorySize: props.memorySize ?? 128,
             ephemeralStorageSize: props.ephemeralStorageSize
                 ? Size.mebibytes(props.ephemeralStorageSize)
                 : undefined,
-            description: props.lambdaDescription || `${id} Lambda`,
+            description: props.lambdaDescription ?? `${id} Lambda`,
             environment: props.environment,
             logGroup: new LogGroup(scope, `${id}LogGroup`, {
-                retention: RetentionDays.ONE_WEEK
+                retention: props.logGroupRetention ?? RetentionDays.ONE_WEEK
             })
         });
         addPoliciesToRole(this, props.inlinePolicy);
+        applyRoleDescription(this, props.roleDescription);
         this.addSecretsSupport(props.secrets, props.ssmSecretsPath, props.secretsImport, props.appName, props.functionName, props.architecture);
         // Sanitise id for CloudFormation output keys (must be alphanumeric)
         const outputName = toPascalCase(id);
         if (props.enableFunctionUrl) {
             const functionUrl = this.addFunctionUrl({
-                authType: props.functionUrlAuthType || FunctionUrlAuthType.AWS_IAM,
+                authType: props.functionUrlAuthType ?? FunctionUrlAuthType.AWS_IAM,
                 cors: props.functionUrlCors,
                 invokeMode: props.functionUrlInvokeMode
             });
@@ -95,14 +112,8 @@ export class LambdaFunction extends Function {
             value: this.functionArn,
             description: `${id} Function ARN`
         });
-        if (props.scheduleExpression) {
-            const rule = new Rule(this, `${id}ScheduleRule`, {
-                schedule: Schedule.expression(props.scheduleExpression)
-            });
-            rule.addTarget(new LambdaTarget(this));
-        }
         if (props.alertsTopic && props.alarms !== false) {
-            const timeoutSeconds = props.timeout ?? 300;
+            const timeoutSeconds = props.timeout ?? LAMBDA_DEFAULT_TIMEOUT_SECONDS;
             createLambdaAlarms({
                 scope: this,
                 functionName: id,
@@ -194,25 +205,6 @@ export class LambdaFunction extends Function {
         const eventSource = new S3EventSource(bucket, s3EventSourceProps);
         this.addEventSource(eventSource);
     }
-    /**
-     * Add an EventBridge rule as an event source for this Lambda function.
-     * This will trigger the Lambda when events matching the pattern are published.
-     * Useful for scheduled jobs, cross-service event handling, and custom event patterns.
-     */
-    addEventBridgeEventSource(ruleId, options) {
-        if (!options.schedule && !options.eventPattern) {
-            throw new Error("EventBridge rule requires either schedule or eventPattern");
-        }
-        const rule = new Rule(this, ruleId, {
-            schedule: options.schedule
-                ? Schedule.expression(options.schedule)
-                : undefined,
-            eventPattern: options.eventPattern,
-            description: options.description
-        });
-        rule.addTarget(new LambdaTarget(this));
-        return rule;
-    }
     /**
      * Add secrets support using AWS Parameters and Secrets Lambda Extension.
      *

package/dist/lib/resources/aws/compute/lifecycleHookLambda.source.cjs

@@ -0,0 +1,192 @@
+/**
+ * ECS deployment lifecycle hook (PRE_SCALE_UP) runner. Inlined into a Lambda
+ * at synth time by ecsLifecycleHookMigration.ts.
+ *
+ * Re-invocation safety: ECS hook responses do NOT carry state between
+ * IN_PROGRESS invocations. On every invocation we reconstruct the
+ * deterministic startedBy tag from the event's targetServiceRevisionArn and
+ * use ListTasks to find an existing running migration. RunTask fires only on
+ * the first invocation.
+ *
+ * CommonJS rather than ESM because Code.fromInline lands the source as
+ * `index.js`, which Lambda treats as CommonJS by default.
+ */
+const {
+  ECSClient,
+  RunTaskCommand,
+  DescribeTasksCommand,
+  ListTasksCommand
+} = require("@aws-sdk/client-ecs");
+
+const POLL_INTERVAL_MS = 5_000;
+const MAX_POLLS_PER_INVOCATION = 20;
+const HOOK_CALLBACK_DELAY_SECONDS = 30;
+
+let _defaultClient;
+function getDefaultClient() {
+  if (!_defaultClient) _defaultClient = new ECSClient({});
+  return _defaultClient;
+}
+
+function startedByTag(targetServiceRevisionArn) {
+  // ECS startedBy is bounded to 36 chars; revision id alone is shorter.
+  const suffix =
+    String(targetServiceRevisionArn || "")
+      .split("/")
+      .pop() || "unknown";
+  return `fjall-migrate-${suffix}`.slice(0, 36);
+}
+
+function buildContainerOverrides(
+  name,
+  command,
+  image,
+  entryPoint,
+  environment
+) {
+  const override = { name, command };
+  if (image) override.image = image;
+  if (entryPoint && entryPoint.length > 0) override.entryPoint = entryPoint;
+  if (environment && Object.keys(environment).length > 0) {
+    override.environment = Object.entries(environment).map(([key, value]) => ({
+      name: key,
+      value
+    }));
+  }
+  return [override];
+}
+
+async function findExistingTaskArn(client, clusterArn, startedBy) {
+  const result = await client.send(
+    new ListTasksCommand({ cluster: clusterArn, startedBy })
+  );
+  if (!result.taskArns || result.taskArns.length === 0) return undefined;
+  return result.taskArns[0];
+}
+
+async function pollTaskUntilStopped(client, clusterArn, taskArn, sleep) {
+  const sleepFn =
+    sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  for (let i = 0; i < MAX_POLLS_PER_INVOCATION; i++) {
+    const desc = await client.send(
+      new DescribeTasksCommand({ cluster: clusterArn, tasks: [taskArn] })
+    );
+    const task = desc.tasks && desc.tasks[0];
+    if (!task) {
+      return { hookStatus: "FAILED", reason: "DescribeTasks returned no task" };
+    }
+    if (task.lastStatus === "STOPPED") {
+      const exitCode =
+        task.containers && task.containers[0]
+          ? task.containers[0].exitCode
+          : undefined;
+      if (exitCode === 0) return { hookStatus: "SUCCEEDED" };
+      return {
+        hookStatus: "FAILED",
+        reason: `Task exited ${exitCode}: ${task.stoppedReason || "no reason"}`
+      };
+    }
+    if (i < MAX_POLLS_PER_INVOCATION - 1) {
+      await sleepFn(POLL_INTERVAL_MS);
+    }
+  }
+  return {
+    hookStatus: "IN_PROGRESS",
+    callBackDelay: HOOK_CALLBACK_DELAY_SECONDS
+  };
+}
+
+async function runHandler(event, deps) {
+  const client = (deps && deps.client) || getDefaultClient();
+  const sleep = deps && deps.sleep;
+  const config = JSON.parse(
+    (deps && deps.migrateConfig) || process.env.MIGRATE_CONFIG
+  );
+  const startedBy = startedByTag(event && event.targetServiceRevisionArn);
+
+  const existingTaskArn = await findExistingTaskArn(
+    client,
+    config.clusterArn,
+    startedBy
+  );
+  if (existingTaskArn) {
+    return pollTaskUntilStopped(
+      client,
+      config.clusterArn,
+      existingTaskArn,
+      sleep
+    );
+  }
+
+  const result = await client.send(
+    new RunTaskCommand({
+      cluster: config.clusterArn,
+      taskDefinition: config.taskDefinitionArn,
+      launchType: "FARGATE",
+      networkConfiguration: {
+        awsvpcConfiguration: config.networkConfiguration
+      },
+      overrides: {
+        containerOverrides: buildContainerOverrides(
+          config.name,
+          config.command,
+          config.hasSeparateMigrationTaskDef ? undefined : config.image,
+          config.hasSeparateMigrationTaskDef ? undefined : config.entryPoint,
+          config.environment
+        )
+      },
+      startedBy
+    })
+  );
+  const taskArn =
+    result.tasks && result.tasks[0] ? result.tasks[0].taskArn : undefined;
+  if (!taskArn) {
+    return {
+      hookStatus: "FAILED",
+      reason: "RunTask did not return a task ARN"
+    };
+  }
+
+  return pollTaskUntilStopped(client, config.clusterArn, taskArn, sleep);
+}
+
+exports.handler = async (event) => {
+  // Log invocation context + outcome — ECS hooks only surface "hook execution
+  // failure" to the deployment; without these the Lambda log is silent and
+  // the failure cause is unrecoverable.
+  console.log(
+    JSON.stringify({
+      msg: "lifecycle-hook-invoked",
+      targetServiceRevisionArn:
+        (event && event.targetServiceRevisionArn) || "(missing)",
+      executionId:
+        (event &&
+          event.executionDetails &&
+          event.executionDetails.executionId) ||
+        "(missing)"
+    })
+  );
+  try {
+    const result = await runHandler(event);
+    console.log(JSON.stringify({ msg: "lifecycle-hook-result", ...result }));
+    return result;
+  } catch (err) {
+    const reason = err && err.message ? err.message : String(err);
+    const stack = err && err.stack ? err.stack : undefined;
+    console.error(
+      JSON.stringify({ msg: "lifecycle-hook-crashed", reason, stack })
+    );
+    return { hookStatus: "FAILED", reason: `Runner crashed: ${reason}` };
+  }
+};
+
+exports._internals = {
+  startedByTag,
+  buildContainerOverrides,
+  findExistingTaskArn,
+  pollTaskUntilStopped,
+  runHandler,
+  POLL_INTERVAL_MS,
+  MAX_POLLS_PER_INVOCATION,
+  HOOK_CALLBACK_DELAY_SECONDS
+};

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

@@ -0,0 +1,104 @@
+import { type AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
+import { Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { EbsDeviceVolumeType, Volume } from "aws-cdk-lib/aws-ec2";
+import { Construct } from "constructs";
+import { LambdaFunction } from "./lambda.js";
+import { SQSQueue } from "../messaging/sqs.js";
+/**
+ * Description prefix baked into the LAUNCHING Lambda + execution-role
+ * descriptions. Tests grep CFN output for this needle to locate the function
+ * across stacks; keep it here as the single source of truth so a rename does
+ * not silently break the test query.
+ */
+export declare const PERSISTENT_DATA_VOLUME_LAUNCHING_DESCRIPTION = "PersistentDataVolume launching handler";
+export declare const PERSISTENT_DATA_VOLUME_TAG_LIFECYCLE = "fjall:Lifecycle";
+export declare const PERSISTENT_DATA_VOLUME_TAG_LIFECYCLE_VALUE = "data-volume";
+export declare const PERSISTENT_DATA_VOLUME_TAG_OWNER_LOGICAL_ID = "fjall:OwnerLogicalId";
+export declare const PERSISTENT_DATA_VOLUME_TAG_STACK_ID = "fjall:StackId";
+export interface PersistentDataVolumeProps {
+    /** ASG whose EC2_INSTANCE_LAUNCHING transitions trigger the re-attach. */
+    autoScalingGroup: AutoScalingGroup;
+    /** Size in GiB. */
+    sizeGb: number;
+    /** Device path the bootstrap script expects (e.g. /dev/xvdf). */
+    deviceName: string;
+    /**
+     * Availability zone the volume lives in. MUST match the ASG's single AZ —
+     * standalone EBS volumes are AZ-local and cannot follow a multi-AZ ASG.
+     * Pass `Stack.of(this).availabilityZones[0]` from a single-AZ-constrained
+     * consumer.
+     */
+    availabilityZone: string;
+    /** EBS volume type. Defaults to gp3. */
+    volumeType?: EbsDeviceVolumeType;
+    /** Provisioned IOPS (gp3/io1/io2 only). */
+    iops?: number;
+    /** Throughput in MiB/s (gp3 only). */
+    throughputMbps?: number;
+}
+/**
+ * Standalone EBS data volume + ASG `EC2_INSTANCE_LAUNCHING` hook that
+ * re-attaches the same physical volume across instance refreshes.
+ *
+ * Pairs with the TERMINATING-side DetachVolume branch in
+ * `ec2GracefulTerminationLambda.source.cjs` (see `DetachVolumeCommand` import
+ * + invocation) wired by `ec2GracefulTerminationHandler.ts` when
+ * `dataVolumeOwnerLogicalId` is forwarded from `Ec2Instance`. The two
+ * Lambdas form a closed re-attach contract.
+ *
+ * Volume tagging: three tags carry the re-attach identity —
+ *   `fjall:Lifecycle = data-volume` (constant; gates IAM scoping)
+ *   `fjall:OwnerLogicalId = <this.node.path>` (per-construct, stable across
+ *     instance refreshes in one stack so the Lambda re-finds the same volume)
+ *   `fjall:StackId = <Aws.STACK_ID>` (per-stack-creation discriminator;
+ *     CloudFormation issues a fresh StackId for every CREATE, so orphans
+ *     from prior failed deploys or aborted `cdk destroy` runs carry a stale
+ *     StackId and cannot collide with the new deploy's volume)
+ *
+ * The LAUNCHING Lambda filters DescribeVolumes by all three tags AND ABANDONs
+ * on multi-match. The TERMINATING handler MUST be configured with the same
+ * `ownerLogicalId` (and is in the same stack, so shares the StackId
+ * automatically) to locate the volume for detach.
+ *
+ * Why three tags. The first two are stable per logical construct; without
+ * the StackId discriminator, every prior-iteration orphan (CREATE_ROLLBACK,
+ * UPDATE_ROLLBACK_FAILED, DELETE_FAILED, manual interruption) that CFN
+ * cannot guarantee to delete on rollback would multi-match the LAUNCHING
+ * filter and force ABANDON on the next deploy. The StackId tag makes the
+ * system orphan-tolerant by construction — orphans simply don't match.
+ *
+ * Removal policy `SNAPSHOT` is independent: it covers data preservation
+ * across clean `cdk destroy`, not orphan defence. Recovery from a snapshot
+ * after destroy is still a manual restore-with-new-tags step (intentionally
+ * undocumented as a runbook — `cdk destroy` of a stateful stack is rare
+ * enough that ad-hoc recovery is acceptable).
+ */
+export declare class PersistentDataVolume extends Construct {
+    readonly volume: Volume;
+    readonly lambda: LambdaFunction;
+    readonly queue: SQSQueue;
+    /**
+     * Identifier used as the `fjall:OwnerLogicalId` tag on the volume and the
+     * `OWNER_LOGICAL_ID` env on the Lambda. Consumers MUST pass this exact
+     * value to the TERMINATING handler so it locates the same volume for
+     * detach. Derived from `this.node.path`; renaming or reparenting any
+     * ancestor changes the value, which breaks the re-attach chain (Lambda
+     * filter no longer matches, new instance fails its launch hook). Rename
+     * across an existing deployment is a manual snapshot-restore step.
+     */
+    readonly ownerLogicalId: string;
+    readonly attachFailureAlarm: Alarm;
+    constructor(scope: Construct, id: string, props: PersistentDataVolumeProps);
+}
+declare function validatePersistentDataVolumeProps(props: PersistentDataVolumeProps): void;
+export declare const _internals: {
+    LAUNCHING_LAMBDA_SOURCE_FILE: string;
+    LAMBDA_TIMEOUT_SECONDS: number;
+    LAUNCHING_HOOK_HEARTBEAT_SECONDS: number;
+    QUEUE_VISIBILITY_TIMEOUT_SECONDS: number;
+    ALARM_EVALUATION_PERIODS: number;
+    ALARM_DATAPOINTS_TO_ALARM: number;
+    ALARM_THRESHOLD: number;
+    validatePersistentDataVolumeProps: typeof validatePersistentDataVolumeProps;
+};
+export {};

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

@@ -0,0 +1,245 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Aws, Duration, RemovalPolicy, Size, Stack, Tags } from "aws-cdk-lib";
+import { DefaultResult, LifecycleTransition } from "aws-cdk-lib/aws-autoscaling";
+import { Alarm, ComparisonOperator, Metric, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+import { EbsDeviceVolumeType, Volume } from "aws-cdk-lib/aws-ec2";
+import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { Code, Runtime } from "aws-cdk-lib/aws-lambda";
+import { RetentionDays } from "aws-cdk-lib/aws-logs";
+import { Construct } from "constructs";
+import { attachInlineAsgLifecycleHook } from "./asgInlineLifecycleHook.js";
+import { LambdaFunction } from "./lambda.js";
+import { SQSQueue } from "../messaging/sqs.js";
+import { Subscription } from "../messaging/subscription.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const LAUNCHING_LAMBDA_SOURCE_FILE = "persistentDataVolumeLambda.source.cjs";
+/**
+ * Description prefix baked into the LAUNCHING Lambda + execution-role
+ * descriptions. Tests grep CFN output for this needle to locate the function
+ * across stacks; keep it here as the single source of truth so a rename does
+ * not silently break the test query.
+ */
+export const PERSISTENT_DATA_VOLUME_LAUNCHING_DESCRIPTION = "PersistentDataVolume launching handler";
+const LAMBDA_TIMEOUT_SECONDS = 180;
+// Heartbeat must comfortably exceed the Lambda's 90s attach deadline.
+const LAUNCHING_HOOK_HEARTBEAT_SECONDS = 300;
+const QUEUE_VISIBILITY_TIMEOUT_SECONDS = 240;
+export const PERSISTENT_DATA_VOLUME_TAG_LIFECYCLE = "fjall:Lifecycle";
+export const PERSISTENT_DATA_VOLUME_TAG_LIFECYCLE_VALUE = "data-volume";
+export const PERSISTENT_DATA_VOLUME_TAG_OWNER_LOGICAL_ID = "fjall:OwnerLogicalId";
+export const PERSISTENT_DATA_VOLUME_TAG_STACK_ID = "fjall:StackId";
+const ALARM_EVALUATION_PERIODS = 3;
+const ALARM_DATAPOINTS_TO_ALARM = 3;
+const ALARM_THRESHOLD = 1;
+/**
+ * Standalone EBS data volume + ASG `EC2_INSTANCE_LAUNCHING` hook that
+ * re-attaches the same physical volume across instance refreshes.
+ *
+ * Pairs with the TERMINATING-side DetachVolume branch in
+ * `ec2GracefulTerminationLambda.source.cjs` (see `DetachVolumeCommand` import
+ * + invocation) wired by `ec2GracefulTerminationHandler.ts` when
+ * `dataVolumeOwnerLogicalId` is forwarded from `Ec2Instance`. The two
+ * Lambdas form a closed re-attach contract.
+ *
+ * Volume tagging: three tags carry the re-attach identity —
+ *   `fjall:Lifecycle = data-volume` (constant; gates IAM scoping)
+ *   `fjall:OwnerLogicalId = <this.node.path>` (per-construct, stable across
+ *     instance refreshes in one stack so the Lambda re-finds the same volume)
+ *   `fjall:StackId = <Aws.STACK_ID>` (per-stack-creation discriminator;
+ *     CloudFormation issues a fresh StackId for every CREATE, so orphans
+ *     from prior failed deploys or aborted `cdk destroy` runs carry a stale
+ *     StackId and cannot collide with the new deploy's volume)
+ *
+ * The LAUNCHING Lambda filters DescribeVolumes by all three tags AND ABANDONs
+ * on multi-match. The TERMINATING handler MUST be configured with the same
+ * `ownerLogicalId` (and is in the same stack, so shares the StackId
+ * automatically) to locate the volume for detach.
+ *
+ * Why three tags. The first two are stable per logical construct; without
+ * the StackId discriminator, every prior-iteration orphan (CREATE_ROLLBACK,
+ * UPDATE_ROLLBACK_FAILED, DELETE_FAILED, manual interruption) that CFN
+ * cannot guarantee to delete on rollback would multi-match the LAUNCHING
+ * filter and force ABANDON on the next deploy. The StackId tag makes the
+ * system orphan-tolerant by construction — orphans simply don't match.
+ *
+ * Removal policy `SNAPSHOT` is independent: it covers data preservation
+ * across clean `cdk destroy`, not orphan defence. Recovery from a snapshot
+ * after destroy is still a manual restore-with-new-tags step (intentionally
+ * undocumented as a runbook — `cdk destroy` of a stateful stack is rare
+ * enough that ad-hoc recovery is acceptable).
+ */
+export class PersistentDataVolume extends Construct {
+    volume;
+    lambda;
+    queue;
+    /**
+     * Identifier used as the `fjall:OwnerLogicalId` tag on the volume and the
+     * `OWNER_LOGICAL_ID` env on the Lambda. Consumers MUST pass this exact
+     * value to the TERMINATING handler so it locates the same volume for
+     * detach. Derived from `this.node.path`; renaming or reparenting any
+     * ancestor changes the value, which breaks the re-attach chain (Lambda
+     * filter no longer matches, new instance fails its launch hook). Rename
+     * across an existing deployment is a manual snapshot-restore step.
+     */
+    ownerLogicalId;
+    attachFailureAlarm;
+    constructor(scope, id, props) {
+        super(scope, id);
+        validatePersistentDataVolumeProps(props);
+        this.ownerLogicalId = this.node.path;
+        this.volume = new Volume(this, "Volume", {
+            availabilityZone: props.availabilityZone,
+            size: Size.gibibytes(props.sizeGb),
+            volumeType: props.volumeType ?? EbsDeviceVolumeType.GP3,
+            encrypted: true,
+            ...(props.iops !== undefined && { iops: props.iops }),
+            ...(props.throughputMbps !== undefined && {
+                throughput: props.throughputMbps
+            })
+        });
+        this.volume.applyRemovalPolicy(RemovalPolicy.SNAPSHOT);
+        Tags.of(this.volume).add(PERSISTENT_DATA_VOLUME_TAG_LIFECYCLE, PERSISTENT_DATA_VOLUME_TAG_LIFECYCLE_VALUE);
+        Tags.of(this.volume).add(PERSISTENT_DATA_VOLUME_TAG_OWNER_LOGICAL_ID, this.ownerLogicalId);
+        Tags.of(this.volume).add(PERSISTENT_DATA_VOLUME_TAG_STACK_ID, Aws.STACK_ID);
+        this.queue = new SQSQueue(this, `${id}Queue`, {
+            visibilityTimeout: QUEUE_VISIBILITY_TIMEOUT_SECONDS,
+            deadLetterQueue: { enabled: true, maxReceiveCount: 5 }
+        });
+        const sourcePath = path.resolve(__dirname, LAUNCHING_LAMBDA_SOURCE_FILE);
+        const source = readFileSync(sourcePath, "utf-8");
+        const stack = Stack.of(this);
+        const volumeArnPattern = `arn:${stack.partition}:ec2:${stack.region}:${stack.account}:volume/*`;
+        const instanceArnPattern = `arn:${stack.partition}:ec2:${stack.region}:${stack.account}:instance/*`;
+        // Account/region-scoped wildcard rather than the specific ASG ARN. The
+        // specific ARN would create an implicit CFN Ref to the ASG, forcing the
+        // Lambda's IAM Policy to wait for ASG CREATE_COMPLETE. The ASG cannot
+        // complete until the Lambda calls CompleteLifecycleAction on its first
+        // instance — the wildcard breaks the deadlock without widening blast
+        // radius: the Lambda is only invoked by its own SQS queue, which is fed
+        // by an EventBridge rule discriminating by the stack-scoped
+        // LifecycleHookName below.
+        const asgArnWildcard = `arn:${stack.partition}:autoscaling:${stack.region}:${stack.account}:autoScalingGroup:*:autoScalingGroupName/*`;
+        const describeVolumesPolicy = new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: ["ec2:DescribeVolumes"],
+            resources: ["*"]
+        });
+        // Split volume + instance: StringEqualsIfExists granted AttachVolume on
+        // any untagged resource (incl. arbitrary instances). Use StringEquals on
+        // the volume side; instances launched by the ASG carry no lifecycle tag.
+        const attachVolumeOnTaggedVolumePolicy = new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: ["ec2:AttachVolume"],
+            resources: [volumeArnPattern],
+            conditions: {
+                StringEquals: {
+                    [`aws:ResourceTag/${PERSISTENT_DATA_VOLUME_TAG_LIFECYCLE}`]: PERSISTENT_DATA_VOLUME_TAG_LIFECYCLE_VALUE,
+                    [`aws:ResourceTag/${PERSISTENT_DATA_VOLUME_TAG_STACK_ID}`]: Aws.STACK_ID
+                }
+            }
+        });
+        const attachVolumeOnInstancePolicy = new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: ["ec2:AttachVolume"],
+            resources: [instanceArnPattern]
+        });
+        const completeLifecyclePolicy = new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: ["autoscaling:CompleteLifecycleAction"],
+            resources: [asgArnWildcard]
+        });
+        this.lambda = new LambdaFunction(this, `${id}Fn`, {
+            runtime: Runtime.NODEJS_22_X,
+            handler: "index.handler",
+            code: Code.fromInline(source),
+            lambdaDescription: `${id} ${PERSISTENT_DATA_VOLUME_LAUNCHING_DESCRIPTION}`,
+            roleDescription: `Execution role for ${id} ${PERSISTENT_DATA_VOLUME_LAUNCHING_DESCRIPTION}`,
+            timeout: LAMBDA_TIMEOUT_SECONDS,
+            memorySize: 256,
+            logGroupRetention: RetentionDays.ONE_MONTH,
+            environment: {
+                OWNER_LOGICAL_ID: this.ownerLogicalId,
+                STACK_ID: Aws.STACK_ID,
+                DEVICE_NAME: props.deviceName
+            },
+            inlinePolicy: [
+                describeVolumesPolicy,
+                attachVolumeOnTaggedVolumePolicy,
+                attachVolumeOnInstancePolicy,
+                completeLifecyclePolicy
+            ]
+        });
+        this.lambda.addSqsEventSource(this.queue.getQueue());
+        // Hook name embeds Aws.STACK_NAME (a pseudo-parameter Ref, NOT a resource
+        // Ref — does not create a CFN dep) so that LifecycleHookName alone is
+        // sufficient to discriminate across stacks in the EB pattern below. The
+        // sibling TERMINATING hook uses "-terminating" so the two never collide
+        // within a single stack either.
+        const launchingHookName = `${Aws.STACK_NAME}-${id}-launching`;
+        attachInlineAsgLifecycleHook(this, `${id}LaunchingHook`, {
+            autoScalingGroup: props.autoScalingGroup,
+            hookName: launchingHookName,
+            lifecycleTransition: LifecycleTransition.INSTANCE_LAUNCHING,
+            defaultResult: DefaultResult.ABANDON,
+            heartbeatTimeoutSeconds: LAUNCHING_HOOK_HEARTBEAT_SECONDS
+        });
+        // Pattern discriminates by LifecycleHookName only — the hook name carries
+        // Aws.STACK_NAME so it is unique per stack. AutoScalingGroupName would
+        // also discriminate but creates an implicit Ref to the ASG, blocking the
+        // EB rule on ASG CREATE_COMPLETE (which can't happen without this Lambda
+        // running — the deadlock that motivated the wildcard above).
+        new Subscription(this, `${id}LaunchingSub`, {
+            pattern: {
+                source: ["aws.autoscaling"],
+                detailType: ["EC2 Instance-launch Lifecycle Action"],
+                detail: {
+                    LifecycleHookName: [launchingHookName]
+                }
+            },
+            target: this.queue
+        });
+        this.attachFailureAlarm = new Alarm(this, "AttachFailureAlarm", {
+            alarmDescription: `${id} PersistentDataVolume LAUNCHING Lambda errors — ` +
+                `volume re-attach has failed; new instances will not see existing data.`,
+            metric: new Metric({
+                namespace: "AWS/Lambda",
+                metricName: "Errors",
+                dimensionsMap: { FunctionName: this.lambda.functionName },
+                statistic: "Sum",
+                period: Duration.minutes(1)
+            }),
+            threshold: ALARM_THRESHOLD,
+            evaluationPeriods: ALARM_EVALUATION_PERIODS,
+            datapointsToAlarm: ALARM_DATAPOINTS_TO_ALARM,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+            treatMissingData: TreatMissingData.NOT_BREACHING
+        });
+    }
+}
+function validatePersistentDataVolumeProps(props) {
+    if (props.sizeGb <= 0 || !Number.isFinite(props.sizeGb)) {
+        throw new Error(`PersistentDataVolume.sizeGb must be a positive number; got ${props.sizeGb}`);
+    }
+    if (props.deviceName === "") {
+        throw new Error("PersistentDataVolume.deviceName must be non-empty");
+    }
+    if (props.availabilityZone === "") {
+        throw new Error("PersistentDataVolume.availabilityZone must be non-empty");
+    }
+    if (props.throughputMbps !== undefined &&
+        (props.volumeType ?? EbsDeviceVolumeType.GP3) !== EbsDeviceVolumeType.GP3) {
+        throw new Error("PersistentDataVolume.throughputMbps is only valid for gp3 volumes");
+    }
+}
+export const _internals = {
+    LAUNCHING_LAMBDA_SOURCE_FILE,
+    LAMBDA_TIMEOUT_SECONDS,
+    LAUNCHING_HOOK_HEARTBEAT_SECONDS,
+    QUEUE_VISIBILITY_TIMEOUT_SECONDS,
+    ALARM_EVALUATION_PERIODS,
+    ALARM_DATAPOINTS_TO_ALARM,
+    ALARM_THRESHOLD,
+    validatePersistentDataVolumeProps
+};