@fjall/components-infrastructure 5.0.0 → 7.0.0

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

@@ -2,16 +2,18 @@ import { FargateService, Ec2Service, PropagatedTagSource, PlacementStrategy, Asg
 import { Peer, Port, SubnetType, UserData } from "aws-cdk-lib/aws-ec2";
 import { ServicePrincipal } from "aws-cdk-lib/aws-iam";
 import { Role } from "../iam/role.js";
-import { CfnOutput, Duration, Token } from "aws-cdk-lib";
+import { Aws, CfnOutput, Duration } from "aws-cdk-lib";
 import { AdjustmentType, PredefinedMetric, ScalableTarget, ServiceNamespace, StepScalingAction, TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
 import { Alarm, ComparisonOperator, MathExpression } from "aws-cdk-lib/aws-cloudwatch";
 import { ApplicationScalingAction } from "aws-cdk-lib/aws-cloudwatch-actions";
-import { Monitoring } from "aws-cdk-lib/aws-autoscaling";
 import { SecurityGroup } from "../networking/securityGroup.js";
 import { Ec2Instance } from "./ec2.js";
 import { vpcHasNatGateways } from "../../../utils/vpcUtils.js";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
-import { DEFAULT_EC2_INSTANCE_TYPE, DEFAULT_WARM_POOL_MIN_SIZE, DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN, DEFAULT_HEALTH_CHECK_GRACE_SECONDS, DEFAULT_MIN_HEALTHY_PERCENT, DEFAULT_MAX_HEALTHY_PERCENT, DEFAULT_DESIRED_COUNT, inferAmiHardwareType } from "./ecsConstants.js";
+import { DEFAULT_EC2_INSTANCE_TYPE, DEFAULT_EC2_MIN_CAPACITY, DEFAULT_EC2_MAX_CAPACITY, DEFAULT_EC2_INSTANCE_MONITORING, DEFAULT_WARM_POOL_MIN_SIZE, DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN, DEFAULT_HEALTH_CHECK_GRACE_SECONDS, DEFAULT_MIN_HEALTHY_PERCENT, DEFAULT_MAX_HEALTHY_PERCENT, DEFAULT_DESIRED_COUNT, inferAmiHardwareType } from "./ecsConstants.js";
+import { assertAnchorUnique, assertSharedAsgConfigMatches, assertValidCapacitySlot, getEc2ConfigKey, legacyAnchorFromKey, LEGACY_KEY_FIELDS, resolveCapacityAnchor, resolveCapacitySlot } from "./ecsCapacityConfig.js";
+import { lookupCapacityIdentityPin } from "../../../utils/capacityIdentityContext.js";
+import { getCurrentCollector } from "../../../utils/manifestWriter.js";
 import { ScalingType } from "./ecsTypes.js";
 import { isServiceFargate, isServiceEc2 } from "./ecsTaskDefinition.js";
 /**
@@ -26,132 +28,79 @@ export function resolveCircuitBreaker(config) {
     const rollback = config?.rollback ?? true;
     return { enable: true, rollback };
 }
-/**
- * `ec2Config` fields that shape the ASG but are NOT part of
- * {@link getEc2ConfigKey}, split by how a difference can be detected without
- * false positives. A second service whose key matches reuses the first
- * service's ASG, so any of these it sets is silently discarded.
- *
- * Scalars compare by value. `tags` is plain data, so it compares deeply.
- * `machineImage` / `userData` / `blockDevices` are CDK objects with no stable
- * structural identity — two equivalent literals are different references, so
- * only a defined-vs-undefined asymmetry is safe to report. They deliberately
- * under-report: over-reporting is a hard synth failure on config that
- * previously worked, which is the more damaging direction.
- */
-const SCALAR_ASG_FIELDS = [
-    "minCapacity",
-    "maxCapacity",
-    "desiredCapacity",
-    "instanceMonitoring",
-    "associatePublicIpAddress"
-];
-const OPAQUE_ASG_FIELDS = [
-    "machineImage",
-    "userData",
-    "blockDevices"
-];
-function tagRecordsEqual(a, b) {
-    if (a === undefined || b === undefined)
-        return a === b;
-    const aKeys = Object.keys(a);
-    if (aKeys.length !== Object.keys(b).length)
-        return false;
-    return aKeys.every((key) => Object.is(a[key], b[key]));
-}
-function findDifferingAsgFields(ec2Config, origin) {
-    const differing = SCALAR_ASG_FIELDS.filter((field) => !Object.is(ec2Config[field], origin[field]));
-    if (!tagRecordsEqual(ec2Config.tags, origin.tags))
-        differing.push("tags");
-    for (const field of OPAQUE_ASG_FIELDS) {
-        if ((ec2Config[field] === undefined) !== (origin[field] === undefined)) {
-            differing.push(field);
-        }
-    }
-    return differing;
-}
-/**
- * Rejects at synth when a service reusing a shared ASG asks for ASG settings
- * that differ from the ones the ASG was built with — those settings would be
- * silently ignored (same silent-ignore class as `validateEc2ServiceSizing`).
- */
-function assertSharedAsgConfigMatches(serviceName, ec2Config, key, origin) {
-    const differing = findDifferingAsgFields(ec2Config, origin.ec2Config);
-    if (differing.length === 0)
-        return;
-    throw new Error(`Service '${serviceName}': ec2Config ${differing.map((f) => `'${f}'`).join(", ")} ` +
-        `${differing.length === 1 ? "is" : "are"} ignored — it shares an auto scaling group with ` +
-        `service '${origin.serviceName}' (both resolve to EC2 capacity key '${key}'), and that ASG ` +
-        `is built from the first service's ec2Config. Either give the two services the same value ` +
-        `for ${differing.map((f) => `'${f}'`).join(", ")}, or give this service its own ASG by ` +
-        `changing a keyed field ('instanceType', 'amiHardwareType', 'warmPool', ` +
-        `'persistentDataVolume', 'availabilityZones').`);
-}
-/**
- * Generates a unique key for EC2 config so services with matching
- * configurations share an ASG.
- */
-export function getEc2ConfigKey(ec2Config) {
-    const instanceType = ec2Config.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE;
-    const amiHardwareType = ec2Config.amiHardwareType ??
-        (inferAmiHardwareType(instanceType) === AmiHardwareType.ARM
-            ? "ARM"
-            : "STANDARD");
-    const warmPoolKey = ec2Config.warmPool
-        ? `wp${ec2Config.warmPool.minSize ?? DEFAULT_WARM_POOL_MIN_SIZE}-${ec2Config.warmPool.reuseOnScaleIn ?? DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN}`
-        : "nowp";
-    const baseKey = `${instanceType}-${amiHardwareType}-${warmPoolKey}`;
-    // PDV services are implicit singletons — sharing an ASG would let two tasks race for the same EBS volume.
-    const pdv = ec2Config.persistentDataVolume;
-    const extras = [];
-    if (pdv !== undefined) {
-        extras.push(`pdv-${pdv.deviceName}-${pdv.sizeGb}-${stableAzSegment(pdv.availabilityZone)}`);
-    }
-    // Serialise actual AZ names — `az${length}` would let services pinned to different AZs collide on `az1`.
-    // CDK Tokens (env-agnostic stacks) substitute a stable sentinel to keep logical IDs deterministic.
-    if (ec2Config.availabilityZones !== undefined) {
-        const azKey = [...ec2Config.availabilityZones]
-            .map(stableAzSegment)
-            .sort()
-            .join(",");
-        extras.push(`az-${azKey}`);
-    }
-    return extras.length === 0 ? baseKey : `${baseKey}-${extras.join("-")}`;
-}
-function stableAzSegment(az) {
-    return Token.isUnresolved(az) ? "synthAz" : az;
-}
+export { getEc2ConfigKey, validateSharedEc2CapacityConfig } from "./ecsCapacityConfig.js";
 /**
  * Gets or creates an ASG capacity provider for an EC2-backed service.
- * Services with matching EC2 configs share the same ASG.
+ * Services declaring the same capacity SLOT share the same ASG.
+ *
+ * Every CloudFormation identity surface (the four construct-ID prefixes,
+ * the physical service name and everything `Ec2Instance` derives from it)
+ * comes from the slot's identity ANCHOR — `identityAnchor` pin, else the
+ * deploy-injected `fjall:capacityIdentity` context pin, else
+ * `toPascalCase(slot)` — never from the hardware config, so a config change
+ * updates the deployed ASG in place instead of renaming (replacing) it.
  *
- * Mutates `state` to track the provider and first ASG/security group.
+ * Mutates `state` to track the provider and first ASG/security group, and
+ * records the slot's identity alias on the manifest collector (rename
+ * detection and the pin writer consume it).
  */
 export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
     const ec2Config = serviceProps.ec2Config ?? {};
-    const key = getEc2ConfigKey(ec2Config);
-    const existing = state.providers.get(key);
+    const slot = resolveCapacitySlot(ec2Config);
+    assertValidCapacitySlot(slot);
+    const existing = state.providers.get(slot);
     if (existing) {
-        const origin = state.asgOrigins.get(key);
+        const origin = state.asgOrigins.get(slot);
         if (origin !== undefined) {
-            assertSharedAsgConfigMatches(serviceProps.name, ec2Config, key, origin);
+            assertSharedAsgConfigMatches(serviceProps.name, ec2Config, slot, origin);
         }
         return existing;
     }
-    state.asgOrigins.set(key, { serviceName: serviceProps.name, ec2Config });
-    const safeKey = key.replace(/[^a-zA-Z0-9]/g, "");
+    const collector = getCurrentCollector();
+    const appName = collector?.getAppName();
+    const pin = appName !== undefined
+        ? lookupCapacityIdentityPin(ctx.scope, appName, slot)
+        : undefined;
+    const anchor = resolveCapacityAnchor(ec2Config, pin);
+    assertAnchorUnique(slot, anchor, new Map([...state.asgOrigins].map(([s, o]) => [s, o.anchor])));
+    state.asgOrigins.set(slot, {
+        serviceName: serviceProps.name,
+        ec2Config,
+        anchor
+    });
+    const physicalServiceName = `${ctx.props.clusterName}${anchor}`;
+    if (collector !== null) {
+        const legacyKey = getEc2ConfigKey(ec2Config);
+        const legacyAnchor = legacyAnchorFromKey(legacyKey);
+        collector.addCapacityIdentityAlias({
+            appName: collector.getAppName(),
+            slot,
+            clusterName: ctx.props.clusterName,
+            anchor,
+            pinned: pin !== undefined || ec2Config.identityAnchor !== undefined,
+            currentServiceName: physicalServiceName,
+            legacyKey,
+            legacyAnchor,
+            legacyServiceName: `${ctx.props.clusterName}${legacyAnchor}`,
+            legacyKeyFields: [...LEGACY_KEY_FIELDS]
+        });
+    }
     const instanceType = ec2Config.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE;
     const amiHardwareType = ec2Config.amiHardwareType
         ? ec2Config.amiHardwareType === "STANDARD"
             ? AmiHardwareType.STANDARD
             : AmiHardwareType.ARM
         : inferAmiHardwareType(instanceType);
-    const minCapacity = ec2Config.minCapacity ?? 2;
-    const maxCapacity = ec2Config.maxCapacity ?? 3;
+    const minCapacity = ec2Config.minCapacity ?? DEFAULT_EC2_MIN_CAPACITY;
+    const maxCapacity = ec2Config.maxCapacity ?? DEFAULT_EC2_MAX_CAPACITY;
+    // GroupDescription is CFN create-only: a pinned slot must reproduce the
+    // deployed string verbatim or the SG is replaced. New stacks derive it
+    // from the anchor-based physical service name, stable by construction.
     const asgSecurityGroup = ctx.props.cluster?.securityGroup ??
-        new SecurityGroup(ctx.scope, `${safeKey}AsgSecurityGroup`, {
+        new SecurityGroup(ctx.scope, `${anchor}AsgSecurityGroup`, {
             vpc: ctx.cluster.vpc,
-            description: `Security group for ${key} auto scaling group`
+            description: pin?.legacySgDescription ??
+                `Security group for the ${physicalServiceName} auto scaling group`
         });
     if (ctx.directAccessEnabled) {
         for (const service of ctx.props.services) {
@@ -174,12 +123,12 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
         : undefined;
     // userData + role must be set on the LaunchTemplate or AsgCapacityProvider
     // throws at synth (ProvidedLaunchTemplateExposeUser/ExposeDefine).
-    const instanceRole = new Role(ctx.scope, `${safeKey}InstanceRole`, {
+    const instanceRole = new Role(ctx.scope, `${anchor}InstanceRole`, {
         assumedBy: new ServicePrincipal("ec2.amazonaws.com"),
-        description: `EC2 instance role for ${key} ECS capacity`
+        description: `EC2 instance role for the ${slot} ECS capacity slot`
     });
-    const ec2Instance = new Ec2Instance(ctx.scope, `${safeKey}Ec2Instance`, {
-        serviceName: `${ctx.props.clusterName}${safeKey}`,
+    const ec2Instance = new Ec2Instance(ctx.scope, `${anchor}Ec2Instance`, {
+        serviceName: physicalServiceName,
         vpc: ctx.cluster.vpc,
         vpcSubnets: {
             subnetType: hasNat ? SubnetType.PRIVATE_WITH_EGRESS : SubnetType.PUBLIC,
@@ -195,7 +144,7 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
             EcsOptimizedImage.amazonLinux2023(amiHardwareType),
         userData: ec2Config.userData ?? UserData.forLinux(),
         role: instanceRole,
-        instanceMonitoring: ec2Config.instanceMonitoring ?? Monitoring.BASIC,
+        instanceMonitoring: ec2Config.instanceMonitoring ?? DEFAULT_EC2_INSTANCE_MONITORING,
         capacityRebalance: true,
         ecsClusterArn: ctx.cluster.clusterArn,
         ...(ec2Config.desiredCapacity !== undefined && {
@@ -208,6 +157,9 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
             associatePublicIpAddress: ec2Config.associatePublicIpAddress
         }),
         ...(resolvedWarmPool !== undefined && { warmPool: resolvedWarmPool }),
+        ...(ec2Config.updatePolicy !== undefined && {
+            updatePolicy: ec2Config.updatePolicy
+        }),
         ...(ec2Config.persistentDataVolume !== undefined && {
             persistentDataVolume: {
                 ...ec2Config.persistentDataVolume,
@@ -215,12 +167,15 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
                     ctx.props.alertsTopic !== undefined && {
                     alarmTopic: ctx.props.alertsTopic
                 })
-            }
+            },
+            // Pinned slots reproduce the deployed fjall:OwnerLogicalId verbatim —
+            // the re-attach Lambdas filter on it, so a drift strands the volume.
+            dataVolumeStableOwnerId: pin?.legacyOwnerId ?? `${Aws.STACK_NAME}/${anchor}/PersistentDataVolume`
         }),
         ...(ec2Config.tags !== undefined && { tags: ec2Config.tags })
     });
     const asg = ec2Instance.getAutoScalingGroup();
-    const provider = new AsgCapacityProvider(ctx.scope, `${safeKey}AsgCapacityProvider`, {
+    const provider = new AsgCapacityProvider(ctx.scope, `${anchor}AsgCapacityProvider`, {
         autoScalingGroup: asg,
         enableManagedDraining: true,
         // MTP's ProtectedFromScaleIn flag does NOT clear on CP deletion, so
@@ -233,7 +188,7 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
         enableManagedScaling: minCapacity !== maxCapacity
     });
     ctx.cluster.addAsgCapacityProvider(provider);
-    state.providers.set(key, provider);
+    state.providers.set(slot, provider);
     if (!state.autoScalingGroup) {
         state.autoScalingGroup = asg;
     }

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

@@ -22,7 +22,7 @@ import type { ManagedDomainBinding, ManagedDomainExports } from "../../../utils/
 import type { ITopic } from "aws-cdk-lib/aws-sns";
 import type { ILogGroup } from "aws-cdk-lib/aws-logs";
 import type { EcsServiceAlarmThresholds, LogPatternAlarmSpec } from "../monitoring/index.js";
-import { type Ec2InstancePersistentDataVolumeConfig } from "./ec2.js";
+import { type Ec2InstancePersistentDataVolumeConfig, type Ec2InstanceUpdatePolicyConfig } from "./ec2.js";
 export declare enum Protocol {
     HTTP = 0,
     HTTPS = 1
@@ -94,6 +94,26 @@ export type { EcsCapacityProvider };
  * Only used when capacityProvider is "EC2".
  */
 export interface Ec2CapacityConfig {
+    /**
+     * Capacity SLOT — the stable, operator-chosen identity for this ASG within
+     * its cluster. Lowercase kebab (`CAPACITY_SLOT_PATTERN` from `@fjall/util`),
+     * max 64 chars. Default: `"primary"`. Every CloudFormation identity surface
+     * (logical-ID prefixes, physical service name, launch-template name)
+     * derives from the slot's ANCHOR (`toPascalCase(slot)`), never from the
+     * hardware config — changing `instanceType` or any other property updates
+     * the ASG in place instead of renaming (replacing) it. Services declaring
+     * the same slot share its ASG and must agree on every property field
+     * (`assertSharedAsgConfigMatches`).
+     */
+    slot?: string;
+    /**
+     * Explicit identity-anchor pin. When present it wins over both the
+     * slot-derived anchor AND any `fjall:capacityIdentity` context pin. Must
+     * match `CAPACITY_ANCHOR_PATTERN` (alphanumeric, letter first). Primarily
+     * for freezing a deployed pre-6.0 config-derived identity; new stacks
+     * should rely on the slot derivation.
+     */
+    identityAnchor?: string;
     /** EC2 instance type. Default: "t4g.micro" */
     instanceType?: string;
     /** AMI hardware type. Default: "ARM" (Graviton - better cost/performance) */
@@ -151,9 +171,9 @@ export interface Ec2CapacityConfig {
      * Pairs the EC2 capacity ASG with a standalone EBS data volume that
      * re-attaches across instance refreshes. Forwarded to `Ec2Instance` which
      * locates and detaches the volume via TERMINATING/LAUNCHING lifecycle
-     * hooks. Implies a singleton service — do not share an ASG across
-     * services when this is set (`getEc2ConfigKey` adds a discriminator to
-     * keep them apart).
+     * hooks. Implies a singleton service — a second service declaring the
+     * same slot is rejected at synth (`assertSharedAsgConfigMatches`); give
+     * it its own slot instead.
      */
     persistentDataVolume?: Ec2InstancePersistentDataVolumeConfig;
     /**
@@ -163,6 +183,15 @@ export interface Ec2CapacityConfig {
      * Empty-string keys or values are rejected at the resources layer.
      */
     tags?: Record<string, string>;
+    /**
+     * ASG `UpdatePolicy` passthrough, forwarded to `Ec2Instance` verbatim.
+     * Absent → `instanceRefresh` with `minHealthyPercentage 0 /
+     * maxHealthyPercentage 100` when the slot owns a `persistentDataVolume`
+     * (single-attach EBS forbids surge), `100 / 200` otherwise (surge-then
+     * -shrink, no capacity dip). A property field, not identity — changing it
+     * never renames the ASG.
+     */
+    updatePolicy?: Ec2InstanceUpdatePolicyConfig;
 }
 /**
  * Explicit Route53 latency routing policy for the cluster's alias records

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

@@ -3,6 +3,7 @@ import { evaluateBakeGuard } from "@fjall/util/docker";
 import { toKebab, SSM_COMPONENT_PATTERN, SSM_COMPONENT_ERROR, SECRET_NAME_PATTERN, SECRET_NAME_ERROR } from "@fjall/util";
 import { ScalingType } from "./ecsTypes.js";
 import { DEFAULT_EC2_CONTAINER_MEMORY_MIB } from "./ecsConstants.js";
+import { validateSharedEc2CapacityConfig } from "./ecsCapacityConfig.js";
 /**
  * Validates ECS cluster props before construction.
  * Pure function — does not depend on class state.
@@ -196,6 +197,11 @@ export function validateEcsClusterProps(props) {
             }
         }
     }
+    // Cross-service, so it runs after the per-service loop: EC2 services whose
+    // ec2Config resolves to the same capacity key share one ASG — reject config
+    // drift the shared ASG would silently discard, and any sharing of a
+    // persistentDataVolume (singleton) ASG.
+    validateSharedEc2CapacityConfig(props.services);
 }
 /**
  * Rejects service-level task sizing that is silently ignored for EC2 capacity.

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

@@ -19,6 +19,16 @@ 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;
+    /**
+     * Stable owner identifier — becomes the volume's `fjall:OwnerLogicalId`
+     * tag and the Lambdas' `OWNER_LOGICAL_ID` env. An explicit prop (not
+     * `this.node.path`) so the re-attach identity survives construct-tree
+     * refactors: renaming or reparenting an ancestor must never strand the
+     * deployed volume. Must remain byte-stable for the stack's whole life;
+     * for a stack deployed before the identity-anchor era, pass the deployed
+     * tag value verbatim (the pin's `legacyOwnerId`).
+     */
+    stableOwnerId: string;
     /** Size in GiB. */
     sizeGb: number;
     /** Device path the bootstrap script expects (e.g. /dev/xvdf). */
@@ -56,7 +66,7 @@ export interface PersistentDataVolumeProps {
  *
  * 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
+ *   `fjall:OwnerLogicalId = <props.stableOwnerId>` (per-slot, 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
@@ -89,10 +99,10 @@ export declare class PersistentDataVolume extends Construct {
      * 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.
+     * detach. Carries `props.stableOwnerId` verbatim; changing it across an
+     * existing deployment breaks the re-attach chain (Lambda filter no longer
+     * matches, new instance fails its launch hook) — recovery is a manual
+     * snapshot-restore step.
      */
     readonly ownerLogicalId: string;
     readonly attachFailureAlarm: Alarm;

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

@@ -46,7 +46,7 @@ const ALARM_THRESHOLD = 1;
  *
  * 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
+ *   `fjall:OwnerLogicalId = <props.stableOwnerId>` (per-slot, 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
@@ -79,17 +79,17 @@ export class PersistentDataVolume extends Construct {
      * 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.
+     * detach. Carries `props.stableOwnerId` verbatim; changing it across an
+     * existing deployment breaks the re-attach chain (Lambda filter no longer
+     * matches, new instance fails its launch hook) — recovery is a manual
+     * snapshot-restore step.
      */
     ownerLogicalId;
     attachFailureAlarm;
     constructor(scope, id, props) {
         super(scope, id);
         validatePersistentDataVolumeProps(props);
-        this.ownerLogicalId = this.node.path;
+        this.ownerLogicalId = props.stableOwnerId;
         this.volume = new Volume(this, "Volume", {
             availabilityZone: props.availabilityZone,
             size: Size.gibibytes(props.sizeGb),
@@ -157,7 +157,7 @@ export class PersistentDataVolume extends Construct {
             resources: [asgArnWildcard]
         });
         this.lambda = new LambdaFunction(this, `${id}Fn`, {
-            runtime: Runtime.NODEJS_22_X,
+            runtime: Runtime.NODEJS_24_X,
             handler: "index.handler",
             code: Code.fromInline(source),
             lambdaDescription: `${id} ${PERSISTENT_DATA_VOLUME_LAUNCHING_DESCRIPTION}`,
@@ -236,6 +236,9 @@ function validatePersistentDataVolumeProps(props) {
     if (props.deviceName === "") {
         throw new Error("PersistentDataVolume.deviceName must be non-empty");
     }
+    if (props.stableOwnerId === "") {
+        throw new Error("PersistentDataVolume.stableOwnerId must be non-empty");
+    }
     if (props.availabilityZone === "") {
         throw new Error("PersistentDataVolume.availabilityZone must be non-empty");
     }

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

@@ -252,7 +252,7 @@ export class RdsInstance extends Construct {
         const instanceId = ResourceNaming.dbInstanceId(this.constructId);
         const waiterTimeout = Duration.minutes(10);
         const deletionWaiter = new CustomResource(this, `${this.databaseNameValue}DeletionWaiter`, {
-            runtime: Runtime.NODEJS_22_X,
+            runtime: Runtime.NODEJS_24_X,
             timeout: waiterTimeout.plus(Duration.seconds(30)),
             lambdaDescription: `${this.databaseNameValue} deletion waiter`,
             inlineCode: `

package/dist/lib/resources/aws/iam/identityCenter/user.js

@@ -33,7 +33,7 @@ export class IdentityStoreUserProvider extends Construct {
         const identityStoreArn = `arn:${stack.partition}:identitystore::${stack.account}:identitystore/${props.identityStoreId}`;
         const userArnPattern = identityStoreUserArnPattern(stack.partition);
         const handler = new SingletonFunction(this, "Handler", {
-            runtime: Runtime.NODEJS_22_X,
+            runtime: Runtime.NODEJS_24_X,
             code: Code.fromAsset(LAMBDA_ASSET_DIR),
             handler: "index.handler",
             timeout: HANDLER_TIMEOUT_SECONDS,

package/dist/lib/resources/aws/networking/crossAccountReturnRoutes.js

@@ -21,7 +21,7 @@ export class CrossAccountReturnRoutes extends Construct {
     constructor(scope, id, props) {
         super(scope, id);
         this.customResource = new CustomResource(this, "Handler", {
-            runtime: Runtime.NODEJS_22_X,
+            runtime: Runtime.NODEJS_24_X,
             timeout: Duration.minutes(5),
             lambdaDescription: `${id} cross-account return-route manager`,
             roleDescription: `${id} return-route Lambda execution role`,

package/dist/lib/resources/aws/networking/ipamPool.js

@@ -166,7 +166,7 @@ export class IpamPool extends Construct {
                 // On stack deletion, VPC allocations (not managed by CloudFormation)
                 // block CIDR deprovisioning. This custom resource releases them first.
                 const allocationCleanup = new CustomResource(this, `${constructKey}IpamCleanup${regionSuffix}`, {
-                    runtime: Runtime.NODEJS_22_X,
+                    runtime: Runtime.NODEJS_24_X,
                     timeout: Duration.minutes(5),
                     lambdaDescription: `${account} IPAM pool allocation cleanup - ${region}`,
                     properties: {

package/dist/lib/resources/aws/organisation/costAllocationTagActivator.js

@@ -36,7 +36,7 @@ export class CostAllocationTagActivator extends Construct {
         this.lambda = new LambdaFunction(this, "TagActivatorFunction", {
             // Referenced cross-environment by the App messaging stack's schedule rule.
             functionName: PhysicalName.GENERATE_IF_NEEDED,
-            runtime: Runtime.NODEJS_22_X,
+            runtime: Runtime.NODEJS_24_X,
             handler: "index.handler",
             code: Code.fromInline(HANDLER_CODE),
             lambdaDescription: "Auto-discovers and activates cost allocation tags in Cost Explorer",

package/dist/lib/resources/aws/utilities/tlsCertGenerator.js

@@ -66,7 +66,7 @@ export class TlsCertGenerator extends Construct {
             resources: [caCmk.key.keyArn, serverCmk.key.keyArn]
         });
         const cr = new CustomResource(this, "Generator", {
-            runtime: Runtime.NODEJS_22_X,
+            runtime: Runtime.NODEJS_24_X,
             timeout: LAMBDA_TIMEOUT,
             codePath: LAMBDA_ASSET_DIR,
             handler: "index.handler",

package/dist/lib/utils/capacityIdentityContext.d.ts

@@ -0,0 +1,20 @@
+import type { Construct } from "constructs";
+import { type CapacityIdentityPin, type CapacityIdentityWire } from "@fjall/util";
+/**
+ * Reader for the `fjall:capacityIdentity` CDK context the deploy engine
+ * injects (already projected to the current deploy target — see
+ * `@fjall/util § capacityIdentity` for the wire contract).
+ *
+ * Malformed context is a LOUD synth error, never a silent skip: a pin that
+ * fails to apply would synth the slot unpinned, and the resulting template
+ * renames (replaces) every stateful resource in the slot. The deploy-time
+ * rename gate would catch that downstream, but the failure must name the
+ * real cause — the malformed pin — not surface as a mystery rename.
+ */
+export declare function readCapacityIdentityPins(scope: Construct): CapacityIdentityWire | undefined;
+/**
+ * The pin for one `{ appName, slot }`, or undefined when the app/slot is
+ * unpinned. `appName` must be the manifest appName — the same value the pin
+ * writer records.
+ */
+export declare function lookupCapacityIdentityPin(scope: Construct, appName: string, slot: string): CapacityIdentityPin | undefined;

package/dist/lib/utils/capacityIdentityContext.js

@@ -0,0 +1,43 @@
+import { CAPACITY_IDENTITY_CONTEXT_KEY, CapacityIdentityWireSchema } from "@fjall/util";
+/**
+ * Reader for the `fjall:capacityIdentity` CDK context the deploy engine
+ * injects (already projected to the current deploy target — see
+ * `@fjall/util § capacityIdentity` for the wire contract).
+ *
+ * Malformed context is a LOUD synth error, never a silent skip: a pin that
+ * fails to apply would synth the slot unpinned, and the resulting template
+ * renames (replaces) every stateful resource in the slot. The deploy-time
+ * rename gate would catch that downstream, but the failure must name the
+ * real cause — the malformed pin — not surface as a mystery rename.
+ */
+export function readCapacityIdentityPins(scope) {
+    const raw = scope.node.tryGetContext(CAPACITY_IDENTITY_CONTEXT_KEY);
+    if (raw === undefined)
+        return undefined;
+    let value = raw;
+    if (typeof raw === "string") {
+        // `-c key=value` always arrives as a string; tests may set the object form.
+        try {
+            value = JSON.parse(raw);
+        }
+        catch (error) {
+            throw new Error(`${CAPACITY_IDENTITY_CONTEXT_KEY} context is not valid JSON: ` +
+                `${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    const parsed = CapacityIdentityWireSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new Error(`${CAPACITY_IDENTITY_CONTEXT_KEY} context is malformed — refusing to ` +
+            `synth with a pin that cannot apply (an unpinned synth would rename ` +
+            `every stateful resource in the slot): ${parsed.error.message}`);
+    }
+    return parsed.data;
+}
+/**
+ * The pin for one `{ appName, slot }`, or undefined when the app/slot is
+ * unpinned. `appName` must be the manifest appName — the same value the pin
+ * writer records.
+ */
+export function lookupCapacityIdentityPin(scope, appName, slot) {
+    return readCapacityIdentityPins(scope)?.[appName]?.[slot];
+}

package/dist/lib/utils/engineCompat.d.ts

@@ -1,11 +1,18 @@
 import { type EngineCompat } from "@fjall/util/manifest/schemas";
 /**
  * Normalise an npm dependency RANGE to its minimum X.Y.Z floor: strip a leading
- * range operator (`^`, `~`, `>=`, `>`, `=`, `v`) and any prerelease/build
- * metadata, then reconstruct `${major}.${minor}.${patch}` (missing minor/patch
- * default to 0). Returns undefined for anything without a valid integer major —
- * so a non-semver range (a git URL, `*`) yields no floor and the caller omits
- * the field rather than emitting garbage.
+ * inclusive range operator (`^`, `~`, `>=`, `=`, `v`), then reconstruct
+ * `${major}.${minor}.${patch}` (missing minor/patch default to 0).
+ *
+ * Deliberately conservative — returns undefined (→ the caller omits the field,
+ * FM1 degrades to no-op) for every shape whose true floor the first-token strip
+ * would MIS-state rather than merely fail to state:
+ *   - unions (`^3 || ^2` floors at 2.0.0, not the first branch's 3.0.0)
+ *   - strict lower bounds (`>2.1134.0` excludes its own literal)
+ *   - prerelease bounds (`^2.0.0-rc.1` floors below the stripped 2.0.0)
+ *   - non-decimal segments (`1e2`, hex, `2.x`, `*`, git URLs, 4+ segments)
+ * A wrong floor is worse than no floor: over-strict refuses a valid engine,
+ * under-strict admits an incompatible one — both silently.
  */
 export declare function rangeFloor(range: string | undefined): string | undefined;
 /**