@fjall/components-infrastructure 5.0.0 → 7.0.0

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

@@ -0,0 +1,323 @@
+import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
+import { Token } from "aws-cdk-lib";
+import { CAPACITY_ANCHOR_MAX_LENGTH, CAPACITY_ANCHOR_PATTERN, CAPACITY_SLOT_MAX_LENGTH, CAPACITY_SLOT_PATTERN, DEFAULT_CAPACITY_SLOT } from "@fjall/util";
+import { toPascalCase } from "../../../utils/capitaliseString.js";
+import { DEFAULT_EC2_INSTANCE_TYPE, DEFAULT_EC2_MIN_CAPACITY, DEFAULT_EC2_MAX_CAPACITY, DEFAULT_EC2_INSTANCE_MONITORING, DEFAULT_ROLLING_UPDATE_PAUSE_SECONDS, DEFAULT_WARM_POOL_MIN_SIZE, DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN, INSTANCE_REFRESH_DEFAULT_MAX_HEALTHY, INSTANCE_REFRESH_DEFAULT_MIN_HEALTHY, INSTANCE_REFRESH_PDV_MAX_HEALTHY, INSTANCE_REFRESH_PDV_MIN_HEALTHY, inferAmiHardwareType } from "./ecsConstants.js";
+/**
+ * Every `Ec2CapacityConfig` field, classified. The `Record<keyof …, …>`
+ * satisfies-shape is a compile-time exhaustiveness guard in compiled `src/`
+ * (typescript-standards § "Compile-time guards must live in compiled src/"):
+ * adding a field to `Ec2CapacityConfig` without classifying it here fails
+ * `tsc`, so a new ASG-shaping field cannot silently join the "not compared,
+ * silently discarded on a shared ASG" bucket.
+ */
+const EC2_CONFIG_FIELD_ROLES = {
+    slot: "identity",
+    identityAnchor: "identity",
+    instanceType: "property:scalar",
+    amiHardwareType: "property:scalar",
+    minCapacity: "property:scalar",
+    maxCapacity: "property:scalar",
+    desiredCapacity: "property:scalar",
+    instanceMonitoring: "property:scalar",
+    associatePublicIpAddress: "property:scalar",
+    warmPool: "property:deep",
+    persistentDataVolume: "property:deep",
+    availabilityZones: "property:deep",
+    updatePolicy: "property:deep",
+    machineImage: "property:opaque",
+    userData: "property:opaque",
+    blockDevices: "property:opaque",
+    tags: "property:tags",
+    memoryLimitMiB: "validation"
+};
+function fieldsWithRole(role) {
+    return Object.keys(EC2_CONFIG_FIELD_ROLES).filter((field) => EC2_CONFIG_FIELD_ROLES[field] === role);
+}
+const SCALAR_ASG_FIELDS = fieldsWithRole("property:scalar");
+const DEEP_ASG_FIELDS = fieldsWithRole("property:deep");
+const OPAQUE_ASG_FIELDS = fieldsWithRole("property:opaque");
+/** The `"ARM" | "STANDARD"` label the config key and drift compare share. */
+function resolvedAmiHardwareLabel(config) {
+    return (config.amiHardwareType ??
+        (inferAmiHardwareType(config.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE) ===
+            AmiHardwareType.ARM
+            ? "ARM"
+            : "STANDARD"));
+}
+/**
+ * Per-field resolution before a scalar field is compared — the SAME values
+ * the ASG construction applies (`getOrCreateAsgCapacityProvider`), imported
+ * from their `ecsConstants.ts` single source, so an explicit value equal to
+ * the default compares equal to an omitted one instead of tripping the drift
+ * throw on a pair that synthesises identically. Fields with no construction
+ * default (`desiredCapacity`, `associatePublicIpAddress`) compare raw.
+ */
+const SCALAR_ASG_FIELD_RESOLVERS = {
+    instanceType: (c) => c.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE,
+    amiHardwareType: resolvedAmiHardwareLabel,
+    minCapacity: (c) => c.minCapacity ?? DEFAULT_EC2_MIN_CAPACITY,
+    maxCapacity: (c) => c.maxCapacity ?? DEFAULT_EC2_MAX_CAPACITY,
+    instanceMonitoring: (c) => c.instanceMonitoring ?? DEFAULT_EC2_INSTANCE_MONITORING
+};
+function resolvedScalar(config, field) {
+    const resolver = SCALAR_ASG_FIELD_RESOLVERS[field];
+    return resolver !== undefined ? resolver(config) : config[field];
+}
+/**
+ * JSON-stable projections for the plain-data config objects, defaults
+ * resolved. `persistentDataVolume.alarmTopic` is a CDK `ITopic` — projected
+ * to defined-vs-undefined like the opaque fields. `updatePolicy.pauseTime`
+ * is a literal `Duration` — projected to seconds.
+ */
+const DEEP_ASG_FIELD_PROJECTIONS = {
+    warmPool: (c) => c.warmPool === undefined
+        ? undefined
+        : {
+            minSize: c.warmPool.minSize ?? DEFAULT_WARM_POOL_MIN_SIZE,
+            reuseOnScaleIn: c.warmPool.reuseOnScaleIn ?? DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN
+        },
+    persistentDataVolume: (c) => c.persistentDataVolume === undefined
+        ? undefined
+        : {
+            sizeGb: c.persistentDataVolume.sizeGb,
+            deviceName: c.persistentDataVolume.deviceName,
+            availabilityZone: stableAzSegment(c.persistentDataVolume.availabilityZone),
+            volumeType: c.persistentDataVolume.volumeType,
+            iops: c.persistentDataVolume.iops,
+            throughputMbps: c.persistentDataVolume.throughputMbps,
+            alarmTopicDefined: c.persistentDataVolume.alarmTopic !== undefined
+        },
+    availabilityZones: (c) => c.availabilityZones === undefined
+        ? undefined
+        : [...c.availabilityZones].map(stableAzSegment).sort(),
+    updatePolicy: (c) => {
+        // Mirrors resolveUpdatePolicy (ec2.ts): explicit-equal-to-default ≠ drift.
+        const policy = c.updatePolicy ?? { type: "instanceRefresh" };
+        const hasPdv = c.persistentDataVolume !== undefined;
+        switch (policy.type) {
+            case "rollingUpdate":
+                return {
+                    type: policy.type,
+                    pauseTimeSeconds: policy.pauseTime?.toSeconds() ??
+                        DEFAULT_ROLLING_UPDATE_PAUSE_SECONDS
+                };
+            case "instanceRefresh":
+                return {
+                    type: policy.type,
+                    minHealthyPercentage: policy.minHealthyPercentage ??
+                        (hasPdv
+                            ? INSTANCE_REFRESH_PDV_MIN_HEALTHY
+                            : INSTANCE_REFRESH_DEFAULT_MIN_HEALTHY),
+                    maxHealthyPercentage: policy.maxHealthyPercentage ??
+                        (hasPdv
+                            ? INSTANCE_REFRESH_PDV_MAX_HEALTHY
+                            : INSTANCE_REFRESH_DEFAULT_MAX_HEALTHY)
+                };
+            default:
+                return { type: policy.type };
+        }
+    }
+};
+function projectedDeep(config, field) {
+    const projection = DEEP_ASG_FIELD_PROJECTIONS[field];
+    return JSON.stringify(projection !== undefined ? projection(config) : config[field]);
+}
+/** Deep tag-record equality, treating `{}` and absent as the same ASG shape. */
+function tagRecordsEqual(a, b) {
+    const aKeys = a === undefined ? [] : Object.keys(a);
+    const bKeys = b === undefined ? [] : Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    if (a === undefined || b === undefined)
+        return true;
+    return aKeys.every((key) => Object.is(a[key], b[key]));
+}
+function findDifferingAsgFields(ec2Config, origin) {
+    const differing = SCALAR_ASG_FIELDS.filter((field) => !Object.is(resolvedScalar(ec2Config, field), resolvedScalar(origin, field)));
+    for (const field of DEEP_ASG_FIELDS) {
+        if (projectedDeep(ec2Config, field) !== projectedDeep(origin, field)) {
+            differing.push(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;
+}
+/** The slot this ec2Config binds to (`"primary"` when undeclared). */
+export function resolveCapacitySlot(ec2Config) {
+    return ec2Config.slot ?? DEFAULT_CAPACITY_SLOT;
+}
+/** Rejects at synth a slot name outside the kebab grammar. */
+export function assertValidCapacitySlot(slot) {
+    if (slot.length > CAPACITY_SLOT_MAX_LENGTH ||
+        !CAPACITY_SLOT_PATTERN.test(slot)) {
+        throw new Error(`EC2 capacity slot '${slot}' is invalid — slot names are lowercase kebab ` +
+            `(letter first, e.g. 'primary', 'clickhouse-data'), max ` +
+            `${CAPACITY_SLOT_MAX_LENGTH} characters.`);
+    }
+}
+/**
+ * The identity anchor every CloudFormation identity surface derives from.
+ * Precedence: explicit `identityAnchor` config pin, then the deploy-injected
+ * context pin's `legacyAnchor`, then `toPascalCase(slot)`. The anchor grammar
+ * is validated whichever source wins — a bad anchor corrupts every logical
+ * ID and physical name downstream.
+ */
+export function resolveCapacityAnchor(ec2Config, pin) {
+    const anchor = ec2Config.identityAnchor ??
+        pin?.legacyAnchor ??
+        toPascalCase(resolveCapacitySlot(ec2Config));
+    if (anchor.length > CAPACITY_ANCHOR_MAX_LENGTH ||
+        !CAPACITY_ANCHOR_PATTERN.test(anchor)) {
+        throw new Error(`EC2 capacity identity anchor '${anchor}' is invalid — anchors are ` +
+            `alphanumeric, start with a letter, max ${CAPACITY_ANCHOR_MAX_LENGTH} ` +
+            `characters.`);
+    }
+    return anchor;
+}
+/**
+ * Rejects at synth two slots whose anchors collide (`web-1` and `web1` both
+ * normalise to `Web1`) — colliding anchors mean colliding logical IDs.
+ * `anchorsBySlot` carries every anchor already resolved for the cluster.
+ */
+export function assertAnchorUnique(slot, anchor, anchorsBySlot) {
+    for (const [otherSlot, otherAnchor] of anchorsBySlot) {
+        if (otherSlot !== slot && otherAnchor === anchor) {
+            throw new Error(`EC2 capacity slots '${otherSlot}' and '${slot}' both resolve to ` +
+                `identity anchor '${anchor}' — their CloudFormation logical IDs ` +
+                `would collide. Rename one slot (or adjust its identityAnchor).`);
+        }
+    }
+}
+/**
+ * Rejects at synth when a service reusing a shared ASG is incompatible with
+ * it: the slot's identity is contested (`identityAnchor` disagreement), the
+ * origin's `persistentDataVolume` makes the slot a singleton (two tasks
+ * would race to attach the same EBS volume), or the reusing service 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`).
+ */
+export function assertSharedAsgConfigMatches(serviceName, ec2Config, slot, origin) {
+    if (ec2Config.identityAnchor !== origin.ec2Config.identityAnchor) {
+        const describe = (anchor) => anchor === undefined ? "unset" : `'${anchor}'`;
+        throw new Error(`Service '${serviceName}': ec2Config.identityAnchor ` +
+            `(${describe(ec2Config.identityAnchor)}) disagrees with service ` +
+            `'${origin.serviceName}' (${describe(origin.ec2Config.identityAnchor)}) ` +
+            `for capacity slot '${slot}' — a slot has exactly one identity. ` +
+            `Align the pin, or declare a second slot.`);
+    }
+    // Cross-service only: the construction path legitimately re-resolves the
+    // SAME service's provider (e.g. a second task definition riding its ASG),
+    // and that re-entry must not trip the singleton throw.
+    if (origin.ec2Config.persistentDataVolume !== undefined &&
+        serviceName !== origin.serviceName) {
+        throw new Error(`Service '${serviceName}': it declares the same capacity slot ` +
+            `('${slot}') as service '${origin.serviceName}', whose ` +
+            `persistentDataVolume pairs that auto scaling group with a single ` +
+            `EBS data volume. A persistent-data-volume slot is a singleton — ` +
+            `two services sharing its ASG would race to attach the same volume. ` +
+            `Declare a separate slot for this service.`);
+    }
+    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 capacity ` +
+        `slot '${slot}' with service '${origin.serviceName}', and that slot's ` +
+        `ASG is built from the first service's ec2Config. Align the two ` +
+        `services' values for ${differing.map((f) => `'${f}'`).join(", ")}, or ` +
+        `declare a second slot to give this service its own ASG.`);
+}
+/**
+ * Config fields that fed the pre-6.0 (config-keyed) identity derivation —
+ * the "identity derives from …" causes named in manifest identity aliases.
+ */
+export const LEGACY_KEY_FIELDS = [
+    "instanceType",
+    "amiHardwareType",
+    "warmPool",
+    "persistentDataVolume",
+    "availabilityZones"
+];
+/**
+ * The pre-6.0 config-derived identity key. SURVIVES ONLY as the legacy
+ * checksum behind manifest identity-alias hints (`legacyKey`/`legacyAnchor`)
+ * — it feeds no construct IDs, no physical names and no template properties.
+ * ASG sharing keys on the capacity SLOT.
+ */
+export function getEc2ConfigKey(ec2Config) {
+    const instanceType = ec2Config.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE;
+    const amiHardwareType = resolvedAmiHardwareLabel(ec2Config);
+    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}`;
+    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 the checksum 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("-")}`;
+}
+/**
+ * The anchor a pre-6.0 synth derived from a config key — the exact `safeKey`
+ * strip the factory used (`key.replace(/[^a-zA-Z0-9]/g, "")`). Feeds the
+ * manifest alias hints and pin capture; never a live identity surface.
+ */
+export function legacyAnchorFromKey(key) {
+    return key.replace(/[^a-zA-Z0-9]/g, "");
+}
+function stableAzSegment(az) {
+    return Token.isUnresolved(az) ? "synthAz" : az;
+}
+/**
+ * Cross-service capacity-slot compatibility: validates slot grammar, rejects
+ * anchor collisions across slots, and rejects a slot reuse that is
+ * incompatible with the slot's origin — config drift the shared ASG would
+ * silently discard, a contested identity, or a `persistentDataVolume`
+ * singleton being shared. Pure; called from BOTH validation layers —
+ * resources `validateEcsClusterProps` and patterns `validateEcsProps`
+ * (generator-standards § "Validate at the Lowest Layer the Field Belongs To")
+ * — with the same checks at the construction site
+ * (`getOrCreateAsgCapacityProvider`) as defence-in-depth.
+ *
+ * Anchor collisions are checked on the PIN-BLIND anchor (`identityAnchor` or
+ * slot derivation) — this layer is pure and cannot read the deploy-injected
+ * context pins. The factory re-checks with pins applied.
+ */
+export function validateSharedEc2CapacityConfig(services) {
+    const origins = new Map();
+    const anchorsBySlot = new Map();
+    for (const service of services) {
+        if (service.capacityProvider !== "EC2")
+            continue;
+        const ec2Config = service.ec2Config ?? {};
+        const slot = resolveCapacitySlot(ec2Config);
+        assertValidCapacitySlot(slot);
+        const origin = origins.get(slot);
+        if (origin === undefined) {
+            const anchor = resolveCapacityAnchor(ec2Config);
+            assertAnchorUnique(slot, anchor, anchorsBySlot);
+            anchorsBySlot.set(slot, anchor);
+            origins.set(slot, { serviceName: service.name, ec2Config, anchor });
+            continue;
+        }
+        assertSharedAsgConfigMatches(service.name, ec2Config, slot, origin);
+    }
+}

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

@@ -1,3 +1,4 @@
+import { Monitoring } from "aws-cdk-lib/aws-autoscaling";
 import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
 import { RetentionDays } from "aws-cdk-lib/aws-logs";
 export declare const DEFAULT_EC2_INSTANCE_TYPE = "t4g.micro";
@@ -8,6 +9,24 @@ export declare const DEFAULT_LOG_RETENTION = RetentionDays.TWO_WEEKS;
 export declare const DEFAULT_FARGATE_CPU = 256;
 export declare const DEFAULT_FARGATE_MEMORY_MIB = 512;
 export declare const DEFAULT_EC2_CONTAINER_MEMORY_MIB = 1024;
+export declare const DEFAULT_EC2_MIN_CAPACITY = 2;
+export declare const DEFAULT_EC2_MAX_CAPACITY = 3;
+export declare const DEFAULT_EC2_INSTANCE_MONITORING = Monitoring.BASIC;
+/**
+ * `updatePolicy` construction defaults, read at the same two must-agree sites
+ * as the capacity defaults above: `resolveUpdatePolicy` (ec2.ts) applies them
+ * at construction; the shared-ASG drift compare (`ecsCapacityConfig.ts`
+ * DEEP_ASG_FIELD_PROJECTIONS) resolves them so an explicit value equal to the
+ * default never reads as drift. A `persistentDataVolume` ASG cannot surge
+ * (its single-attach EBS volume can only follow one instance), so it
+ * terminates-then-launches (0/100); every other ASG surges-then-shrinks
+ * (100/200) so capacity never dips.
+ */
+export declare const INSTANCE_REFRESH_PDV_MIN_HEALTHY = 0;
+export declare const INSTANCE_REFRESH_PDV_MAX_HEALTHY = 100;
+export declare const INSTANCE_REFRESH_DEFAULT_MIN_HEALTHY = 100;
+export declare const INSTANCE_REFRESH_DEFAULT_MAX_HEALTHY = 200;
+export declare const DEFAULT_ROLLING_UPDATE_PAUSE_SECONDS = 300;
 /**
  * The container hard memory limit for an EC2-capacity ECS service.
  *

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

@@ -1,3 +1,4 @@
+import { Monitoring } from "aws-cdk-lib/aws-autoscaling";
 import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
 import { RetentionDays } from "aws-cdk-lib/aws-logs";
 // Canonical source: @fjall/generator schemas/constants.ts — keep in sync
@@ -16,6 +17,29 @@ export const DEFAULT_LOG_RETENTION = RetentionDays.TWO_WEEKS;
 export const DEFAULT_FARGATE_CPU = 256;
 export const DEFAULT_FARGATE_MEMORY_MIB = 512;
 export const DEFAULT_EC2_CONTAINER_MEMORY_MIB = 1024;
+// Read at two sites that must agree (code-quality § coupled values): the ASG
+// construction (`getOrCreateAsgCapacityProvider`) and the shared-ASG drift
+// compare (`ecsCapacityConfig.ts` SCALAR_ASG_FIELD_DEFAULTS) — the compare
+// resolves the same defaults the construction applies, or an explicit value
+// equal to the default would read as drift.
+export const DEFAULT_EC2_MIN_CAPACITY = 2;
+export const DEFAULT_EC2_MAX_CAPACITY = 3;
+export const DEFAULT_EC2_INSTANCE_MONITORING = Monitoring.BASIC;
+/**
+ * `updatePolicy` construction defaults, read at the same two must-agree sites
+ * as the capacity defaults above: `resolveUpdatePolicy` (ec2.ts) applies them
+ * at construction; the shared-ASG drift compare (`ecsCapacityConfig.ts`
+ * DEEP_ASG_FIELD_PROJECTIONS) resolves them so an explicit value equal to the
+ * default never reads as drift. A `persistentDataVolume` ASG cannot surge
+ * (its single-attach EBS volume can only follow one instance), so it
+ * terminates-then-launches (0/100); every other ASG surges-then-shrinks
+ * (100/200) so capacity never dips.
+ */
+export const INSTANCE_REFRESH_PDV_MIN_HEALTHY = 0;
+export const INSTANCE_REFRESH_PDV_MAX_HEALTHY = 100;
+export const INSTANCE_REFRESH_DEFAULT_MIN_HEALTHY = 100;
+export const INSTANCE_REFRESH_DEFAULT_MAX_HEALTHY = 200;
+export const DEFAULT_ROLLING_UPDATE_PAUSE_SECONDS = 300;
 /**
  * The container hard memory limit for an EC2-capacity ECS service.
  *

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

@@ -49,7 +49,7 @@ export class EcsLifecycleHookMigration extends Construct {
                 : "DISABLED"
         };
         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} ECS deployment lifecycle hook for migration`,

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

@@ -3,7 +3,8 @@ import type { FargateTaskDefinition, Ec2TaskDefinition } from "aws-cdk-lib/aws-e
 import { type ISecurityGroup } from "aws-cdk-lib/aws-ec2";
 import { TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
 import { type AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
-import { type EcsServiceProps, type Ec2CapacityConfig, type QueueScalingResources } from "./ecsTypes.js";
+import { type Ec2AsgOrigin } from "./ecsCapacityConfig.js";
+import { type EcsServiceProps, type QueueScalingResources } from "./ecsTypes.js";
 import type { EcsConstructContext } from "./ecsContext.js";
 /**
  * Resolves the user's `circuitBreaker` config to the CDK
@@ -14,31 +15,34 @@ import type { EcsConstructContext } from "./ecsContext.js";
 export declare function resolveCircuitBreaker(config: false | {
     rollback?: boolean;
 } | undefined): DeploymentCircuitBreaker | undefined;
-/** Mutable state for ASG capacity provider deduplication. */
+/** Mutable state for ASG capacity provider deduplication, keyed by SLOT. */
 export interface AsgCapacityState {
     providers: Map<string, AsgCapacityProvider>;
     /**
-     * The service + ec2Config that first created each keyed ASG, so a later
-     * service sharing the key can be checked against it
-     * ({@link assertSharedAsgConfigMatches}).
+     * The service + ec2Config + anchor that first claimed each capacity slot,
+     * so a later service declaring the slot can be checked against it
+     * ({@link assertSharedAsgConfigMatches}) and anchor collisions across
+     * slots rejected ({@link assertAnchorUnique}).
      */
-    asgOrigins: Map<string, {
-        serviceName: string;
-        ec2Config: Ec2CapacityConfig;
-    }>;
+    asgOrigins: Map<string, Ec2AsgOrigin>;
     autoScalingGroup?: AutoScalingGroup;
     asgSecurityGroup?: ISecurityGroup;
 }
-/**
- * Generates a unique key for EC2 config so services with matching
- * configurations share an ASG.
- */
-export declare function getEc2ConfigKey(ec2Config: Ec2CapacityConfig): string;
+export { getEc2ConfigKey, validateSharedEc2CapacityConfig, type Ec2AsgOrigin, type SharedEc2CapacityServiceInput } 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 declare function getOrCreateAsgCapacityProvider(ctx: EcsConstructContext, serviceProps: EcsServiceProps, state: AsgCapacityState): AsgCapacityProvider;
 /**