@fjall/components-infrastructure 2.30.3 → 2.32.0

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

@@ -0,0 +1,85 @@
+import { Construct } from "constructs";
+import type App from "../../app.js";
+/**
+ * Props for the internal `DevSubstrate` construct.
+ *
+ * Deliberately standalone — NOT a member of the `IPatternProps` union and NOT
+ * registered in `PATTERN_TYPE_VALUES` / the pattern registry / `PatternFactory`.
+ * The substrate is Fjall-managed dev infrastructure, never offered on the
+ * customer create/scaffold surface (design R5). Increments A2–A7 extend this
+ * interface (S3→SQS, compute/network, domain, delegation, `phase`) as each lands.
+ */
+export interface IDevSubstrateProps {
+    /**
+     * Real customer application identifier, surfaced as the `fjall:app` reaper
+     * tag. Distinct from the `fjall-dev-<app>` App identity that drives the
+     * substrate's stack names.
+     */
+    readonly appId: string;
+    /**
+     * Kebab-cased customer app name used to pin the substrate's physical resource
+     * names inside the `fjall-dev-*` fence (cluster identifier, master secret) so
+     * the dev-tier IAM grants match. Single-sourced with the `fjall-dev-<app>` App
+     * identity (design VERDICT-3).
+     */
+    readonly appKebab: string;
+    /**
+     * Aurora PostgreSQL engine version override (default `DEV_AURORA_DEFAULTS`).
+     * Must be `>= 16.3` — the shared cluster runs `serverlessV2MinCapacity` 0,
+     * which needs an auto-pause-capable engine (RdsAurora rejects lower at synth).
+     */
+    readonly engineVersion?: string;
+    /**
+     * When `true`, adopt an already-existing slot image ECR repository
+     * (`fjall-dev-<appKebab>-slots`) by reference instead of creating one — an
+     * import only, emitting no CloudFormation resource (and therefore untaggable).
+     * Defaults to `false`: create and fence-tag the repo. Set on a redeploy into an
+     * account where the repo was provisioned out-of-band.
+     */
+    readonly adoptSlotEcr?: boolean;
+    /**
+     * Deploy phase for the R2 two-step cert-hang guard. `"zone"` synthesises the
+     * `dev.<appDomain>` child zone + cross-account NS delegation only; `"full"`
+     * additionally builds the wildcard cert + :443 listener (A6) — deploy that
+     * only after the delegated NS has propagated, else ACM DNS-validation hangs.
+     * Defaults to `"full"`. Inert unless `domain` is set.
+     */
+    readonly phase?: "zone" | "full";
+    /**
+     * Public domain the substrate hangs a `dev.<appDomain>` child zone under. When
+     * omitted, the substrate stands up no zone/cert (early milestone — G2 reaches
+     * slots via `curl --resolve`).
+     *
+     * `parentDelegationRoleArn`, when present, wires the same-org **Case-1** in-stack
+     * NS delegation (design VD2-a): the child stack's `CrossAccountZoneDelegationRecord`
+     * assumes the parent account's `DelegationRole` by LITERAL ARN and UPSERTs the
+     * child NS into the parent zone. Omit it for a plain externally-owned parent
+     * (Case 3 — manual one-off delegation) or a connected different-org parent
+     * (Case 2 — worker UPSERT, B3b, deferred): the substrate then emits only the
+     * zone + its NS export for out-of-band delegation.
+     */
+    readonly domain?: {
+        readonly appDomain: string;
+        readonly parentDelegationRoleArn?: string;
+    };
+}
+/**
+ * Shared per-app substrate for ephemeral dev/preview slots (fast dev-envs
+ * Phase 3). Stands up the long-lived infrastructure a customer dev team's slots
+ * share — Aurora (A1), an S3→SQS drop (A2), an ECS cluster + slot SG (A2.5), an
+ * ALB with host-header routing (A3) fronted by a Lambda waker (A4), a delegated
+ * child zone (A5) and a wildcard cert (A6) — fenced to the development account.
+ *
+ * Instantiated ONLY via the internal `App.addDevSubstrate(props)`, which scopes
+ * it under the default compute stack so it actually deploys (design VF2). Every
+ * resource it creates carries `fjall:dev = "true"` (the IAM fence tag) and
+ * `fjall:app = <appId>` (the reaper tag) — including resources created through
+ * the app factories in sibling stacks, which are tagged explicitly since the
+ * `Tags.of(this)` aspect only reaches this construct's own scope subtree.
+ */
+export declare class DevSubstrate extends Construct {
+    #private;
+    private readonly app;
+    private readonly appId;
+    constructor(scope: Construct, id: string, app: App, props: IDevSubstrateProps);
+}

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

@@ -0,0 +1,390 @@
+import { CfnOutput, Duration, Stack, Tags } from "aws-cdk-lib";
+import { Port } from "aws-cdk-lib/aws-ec2";
+import { Cluster } from "aws-cdk-lib/aws-ecs";
+import { Repository } from "aws-cdk-lib/aws-ecr";
+import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { Code, Runtime } from "aws-cdk-lib/aws-lambda";
+import { SqsDestination } from "aws-cdk-lib/aws-s3-notifications";
+import { Construct } from "constructs";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { DatabaseFactory } from "./database.js";
+import { StorageFactory } from "./storage.js";
+import { MessagingFactory } from "./messaging.js";
+import { createBaseExecutionRole } from "../../resources/aws/compute/ecsRoles.js";
+import { createApplicationLoadBalancer } from "../../resources/aws/compute/applicationLoadBalancer.js";
+import { addRoutingListener } from "../../resources/aws/compute/listenerRouting.js";
+import { createLambdaTargetGroup } from "../../resources/aws/compute/lambdaAlbTarget.js";
+import { LambdaFunction } from "../../resources/aws/compute/lambda.js";
+import { Ecr } from "../../resources/aws/storage/ecr.js";
+import { SecurityGroup } from "../../resources/aws/networking/securityGroup.js";
+import { HostedZone } from "../../resources/aws/networking/hostedZone.js";
+import { CrossAccountDelegationRecord } from "../../resources/aws/networking/crossAccountDelegationRecord.js";
+import { DomainCertificate } from "../../resources/aws/networking/domainCertificate.js";
+import { Role } from "../../resources/aws/iam/role.js";
+import { toPascalCase } from "../../utils/capitaliseString.js";
+import { DEV_AURORA_DEFAULTS } from "../../resources/aws/database/rdsDefaults.js";
+import { DEV_APP_TAG_KEY, DEV_TAG_KEY, DEV_TAG_VALUE } from "../../utils/devSubstrateTags.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/** Construct id + logical database name for the substrate's shared Aurora. */
+const DEV_SUBSTRATE_DB_ID = "DevSubstrateDb";
+const DEV_SUBSTRATE_DATABASE_NAME = "devsubstrate";
+/** Construct ids for the substrate's S3-drop → SQS event channel. */
+const DEV_SUBSTRATE_DROP_ID = "DevSubstrateDrop";
+const DEV_SUBSTRATE_EVENTS_ID = "DevSubstrateEvents";
+/** Construct ids for the substrate's compute/network layer. */
+const DEV_SUBSTRATE_CLUSTER_ID = "DevSubstrateCluster";
+const DEV_SUBSTRATE_SLOT_SG_ID = "DevSubstrateSlotSg";
+const DEV_SUBSTRATE_SLOT_EXEC_ROLE_ID = "DevSubstrateSlotExecutionRole";
+const DEV_SUBSTRATE_SLOT_ECR_ID = "DevSubstrateSlotEcr";
+/** Construct ids for the substrate's ALB layer. */
+const DEV_SUBSTRATE_ALB_SG_ID = "DevSubstrateAlbSg";
+const DEV_SUBSTRATE_ALB_ID = "DevSubstrateAlb";
+const DEV_SUBSTRATE_HTTP_LISTENER_ID = "DevSubstrateHttpListener";
+/** Construct ids + inline source for the substrate's ALB Lambda waker. */
+const DEV_SUBSTRATE_WAKER_ID = "DevSubstrateWaker";
+const DEV_SUBSTRATE_WAKER_TG_ID = "DevSubstrateWakerTargetGroup";
+const DEV_SUBSTRATE_WAKER_SOURCE_FILE = "devSubstrate.waker.source.cjs";
+const DEV_SUBSTRATE_WAKER_TIMEOUT_SECONDS = 30;
+/** Construct ids for the substrate's delegated `dev.<appDomain>` child zone. */
+const DEV_SUBSTRATE_ZONE_ID = "DevSubstrateZone";
+const DEV_SUBSTRATE_DELEGATION_ID = "DevSubstrateDelegation";
+const DEV_SUBSTRATE_PARENT_ROLE_ID = "DevSubstrateParentDelegationRole";
+/** Construct ids for the substrate's wildcard cert + :443 HTTPS listener (A6). */
+const DEV_SUBSTRATE_CERT_ID = "DevSubstrateCertificate";
+const DEV_SUBSTRATE_HTTPS_LISTENER_ID = "DevSubstrateHttpsListener";
+/**
+ * Default deploy phase when `phase` is omitted — the cert + :443 listener build.
+ * The two-step guard (design R2) sets `"zone"` explicitly for step 1, so the
+ * safe default for a single-shot deploy is the complete substrate.
+ */
+const DEV_SUBSTRATE_DEFAULT_PHASE = "full";
+/**
+ * The substrate's database mode, surfaced to slot-ops as an export so the
+ * hand-created G2 slot knows whether to wire Aurora Data-API creds or a
+ * point-at-existing `DATABASE_URL`. Only `"aurora"` exists today —
+ * `point-at-existing` (GAP-7) is deferred, so this is a fixed value for now.
+ */
+const DEV_SUBSTRATE_DATABASE_MODE = "aurora";
+/**
+ * The container port slots serve HTTP on. Fjall owns the slot image, so this is a
+ * fixed contract: the ALB → slot-SG ingress opens exactly this port and the
+ * host-header rules a slot registers (§5.4) forward to it. The public :80 ALB
+ * front listener is separate.
+ */
+const DEV_SUBSTRATE_SLOT_PORT = 8080;
+/**
+ * Physical-name prefix pinning every substrate resource inside the `fjall-dev-*`
+ * fence. Load-bearing: the dev-tier IAM grants (`@fjall/generator devRolePolicies`)
+ * scope cluster / secret / repo access to this exact prefix, so a drift here
+ * AccessDenies slot ops — single-sourced so the cluster identifier, the master
+ * secret, the ECS cluster name and the slot ECR repo cannot diverge.
+ */
+const devFenceName = (appKebab) => `fjall-dev-${appKebab}`;
+/**
+ * Compile-time parity guard (design T1 / C2-4). `IDevSubstrateProps` — the
+ * `addDevSubstrate` param — and `DevSubstrateSynthProps` — the versioned params
+ * schema the webapp worker (producer) and the Fjall-owned synth entrypoint
+ * (consumer) both import from `@fjall/util` — MUST stay structurally identical, so
+ * a field added to one but not the other fails HERE as a TS error, not as a silent
+ * stale-params synth at deploy.
+ *
+ * Two guards, because neither alone is sufficient:
+ *   - The bidirectional `extends` pair catches a REQUIRED field added to either
+ *     side and any type drift on a shared field (widened/narrowed value type).
+ *   - The key-set equality catches an OPTIONAL field added to one side only —
+ *     which `extends` misses (an extra optional key stays mutually assignable),
+ *     and which is the common case here since almost every prop is optional.
+ */
+const _devSubstratePropsParity = [true, true];
+const _devSubstratePropsKeyParity = true;
+void _devSubstratePropsParity;
+void _devSubstratePropsKeyParity;
+/**
+ * Shared per-app substrate for ephemeral dev/preview slots (fast dev-envs
+ * Phase 3). Stands up the long-lived infrastructure a customer dev team's slots
+ * share — Aurora (A1), an S3→SQS drop (A2), an ECS cluster + slot SG (A2.5), an
+ * ALB with host-header routing (A3) fronted by a Lambda waker (A4), a delegated
+ * child zone (A5) and a wildcard cert (A6) — fenced to the development account.
+ *
+ * Instantiated ONLY via the internal `App.addDevSubstrate(props)`, which scopes
+ * it under the default compute stack so it actually deploys (design VF2). Every
+ * resource it creates carries `fjall:dev = "true"` (the IAM fence tag) and
+ * `fjall:app = <appId>` (the reaper tag) — including resources created through
+ * the app factories in sibling stacks, which are tagged explicitly since the
+ * `Tags.of(this)` aspect only reaches this construct's own scope subtree.
+ */
+export class DevSubstrate extends Construct {
+    app;
+    appId;
+    constructor(scope, id, app, props) {
+        super(scope, id);
+        this.app = app;
+        this.appId = props.appId;
+        this.#tagFenced(this);
+        const database = this.#createDatabase(props);
+        this.#createEventDrop();
+        const { vpc, slotSecurityGroup, cluster, slotExecutionRole, slotRepository } = this.#createComputeNetwork(props, database);
+        const { loadBalancer, httpListener } = this.#createLoadBalancer(vpc, slotSecurityGroup);
+        const wakerTargetGroup = this.#createWaker(props);
+        const { devDomain, httpsListener } = this.#createDomain(props, loadBalancer);
+        this.#emitExports(database, {
+            vpcId: vpc.vpcId,
+            privateSubnetIds: vpc.privateSubnets.map((subnet) => subnet.subnetId),
+            slotSecurityGroupId: slotSecurityGroup.securityGroupId,
+            clusterName: cluster.clusterName,
+            // Slots attach their host-header rule to the frontmost listener — :443 once
+            // the cert exists (the G2 path), else the :80 fallback.
+            slotListenerArn: (httpsListener ?? httpListener).listenerArn,
+            albCloudWatchName: loadBalancer.loadBalancerFullName,
+            // getSnapshotTarget().arn is the only accessor the RelationalDatabase wrapper
+            // exposes for the cluster ARN; it returns databaseCluster.clusterArn.
+            dbClusterArn: database.getSnapshotTarget().arn,
+            dbSecretArn: database.getCredentials().secret.secretArn,
+            slotExecutionRoleArn: slotExecutionRole.roleArn,
+            slotRepositoryUri: slotRepository.repositoryUri,
+            wakerTargetGroupArn: wakerTargetGroup.targetGroupArn,
+            databaseMode: DEV_SUBSTRATE_DATABASE_MODE,
+            devDomain
+        });
+    }
+    #createDatabase(props) {
+        const database = this.app.addDatabase(DatabaseFactory.build(DEV_SUBSTRATE_DB_ID, {
+            type: "Aurora",
+            databaseName: DEV_SUBSTRATE_DATABASE_NAME,
+            clusterIdentifier: devFenceName(props.appKebab),
+            credentialsSecretName: `${devFenceName(props.appKebab)}-master`,
+            engineVersion: props.engineVersion ?? DEV_AURORA_DEFAULTS.ENGINE_VERSION,
+            serverlessV2MinCapacity: DEV_AURORA_DEFAULTS.SERVERLESS_V2_MIN_CAPACITY,
+            serverlessV2MaxCapacity: DEV_AURORA_DEFAULTS.SERVERLESS_V2_MAX_CAPACITY,
+            serverlessV2AutoPauseDuration: Duration.seconds(DEV_AURORA_DEFAULTS.AUTO_PAUSE_SECONDS),
+            enableDataApi: DEV_AURORA_DEFAULTS.ENABLE_DATA_API
+        }));
+        this.#tagFenced(database);
+        return database;
+    }
+    #createEventDrop() {
+        // Bucket and queue MUST share one stack. The OBJECT_CREATED notification and
+        // its auto-generated SQS queue policy reference each other's ARN, so leaving
+        // the queue on the default Messaging stack synthesises a fatal cross-stack
+        // cycle — both are pinned to the compute stack via stackPlacement.
+        const dropBucket = this.app.addStorage(StorageFactory.build(DEV_SUBSTRATE_DROP_ID, {
+            stackPlacement: "compute",
+            versioned: true,
+            encryption: "AES256"
+        }));
+        this.#tagFenced(dropBucket);
+        const eventQueue = this.app.addMessaging(MessagingFactory.build(DEV_SUBSTRATE_EVENTS_ID, {
+            type: "queue"
+        }), { stackPlacement: "compute" });
+        this.#tagFenced(eventQueue);
+        dropBucket.addObjectCreatedNotification(new SqsDestination(eventQueue.getQueue()));
+    }
+    #createComputeNetwork(props, database) {
+        const vpc = this.app.getVpc();
+        // Every resource below is scoped under `this`, so the Tags.of(this) fence
+        // auto-propagates — unlike the factory-created DB/S3/SQS, which land in sibling
+        // stacks and must be tagged explicitly. Names are pinned inside the fjall-dev-*
+        // fence so the scoped slot-ops role's IAM grants reach them.
+        const cluster = new Cluster(this, DEV_SUBSTRATE_CLUSTER_ID, {
+            vpc,
+            clusterName: devFenceName(props.appKebab)
+        });
+        const slotSecurityGroup = new SecurityGroup(this, DEV_SUBSTRATE_SLOT_SG_ID, {
+            vpc,
+            allowAllOutbound: true,
+            description: "Dev substrate slot tasks"
+        });
+        // createBaseExecutionRole DELIBERATELY omits logs (auto-granted only on the
+        // ECS-pattern path via AwsLogDriver.bind()). Slot task-defs reference this
+        // shared role by ARN, so that auto-grant never fires — add the log-write grant
+        // explicitly.
+        const slotExecutionRole = createBaseExecutionRole(this, DEV_SUBSTRATE_SLOT_EXEC_ROLE_ID);
+        const { partition, region, account } = Stack.of(this);
+        slotExecutionRole.addToPolicy(new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: ["logs:CreateLogStream", "logs:PutLogEvents"],
+            resources: [
+                `arn:${partition}:logs:${region}:${account}:log-group:/fjall/dev/${props.appKebab}/slots/*:*`
+            ]
+        }));
+        // Slot-SG → Aurora ingress. Dormant in Data-API mode (Data API reaches the
+        // cluster over HTTPS, not the VPC) — live only in the deferred
+        // point-at-existing pooled mode (GAP-7). The rule lands in the Database stack
+        // referencing the compute-stack slot SG (Database → Compute, one-directional),
+        // so it adds no cross-stack cycle.
+        database.connections.allowDefaultPortFrom(slotSecurityGroup, "Dev substrate slot tasks");
+        // The Ecr wrapper force-emits a `${id}RepositoryName` CFN export, and export
+        // names are account+region-global — so the id MUST be app-scoped or two
+        // substrates in one dev account collide at deploy. Matches
+        // getDefaultContainerRegistry's `${stackPrefix}Ecr`.
+        const slotEcrId = `${toPascalCase(this.app.getName())}${DEV_SUBSTRATE_SLOT_ECR_ID}`;
+        const slotEcrRepositoryName = `${devFenceName(props.appKebab)}-slots`;
+        // Adopt-mode is an import only — no CFN resource, so it carries no fence tags.
+        const slotRepository = props.adoptSlotEcr === true
+            ? Repository.fromRepositoryName(this, slotEcrId, slotEcrRepositoryName)
+            : new Ecr(this, slotEcrId, { repositoryName: slotEcrRepositoryName });
+        return {
+            vpc,
+            slotSecurityGroup,
+            cluster,
+            slotExecutionRole,
+            slotRepository
+        };
+    }
+    #createLoadBalancer(vpc, slotSecurityGroup) {
+        const albSecurityGroup = new SecurityGroup(this, DEV_SUBSTRATE_ALB_SG_ID, {
+            vpc,
+            allowAllOutbound: true,
+            description: "Dev substrate ALB"
+        });
+        // No loadBalancerName: the dev-tier slot-ops ELB grants are account-wide
+        // (`elasticloadbalancing:*:<acct>:*`), not name-prefixed, so the ALB needs no
+        // fence-pinned name — the reaper finds it by the subtree fence tags. A pinned
+        // name would only reintroduce the 32-char ALB-name truncation dance.
+        const loadBalancer = createApplicationLoadBalancer(this, DEV_SUBSTRATE_ALB_ID, { vpc, internetFacing: true, securityGroup: albSecurityGroup });
+        slotSecurityGroup.connections.allowFrom(albSecurityGroup, Port.tcp(DEV_SUBSTRATE_SLOT_PORT), "Dev substrate ALB → slot tasks");
+        // Unconditional 404 default — the substrate's only routes are per-slot
+        // host-header rules, so an unmatched host must 404, never fall through (the ECS
+        // path's 404 is conditional on >=2 routes). The :443 listener + wildcard cert
+        // is phase "full" (A6); open:true opens the custom ALB SG on :80.
+        const httpListener = addRoutingListener(loadBalancer, DEV_SUBSTRATE_HTTP_LISTENER_ID, { port: 80, default404: true });
+        return { loadBalancer, httpListener };
+    }
+    #createWaker(props) {
+        const wakerSecretParam = `/fjall/dev/${props.appKebab}/waker/secret`;
+        const source = readFileSync(path.resolve(__dirname, DEV_SUBSTRATE_WAKER_SOURCE_FILE), "utf-8");
+        const { partition, region, account } = Stack.of(this);
+        // NOT VPC-attached (no `vpc` prop): the waker resumes slots via the AWS
+        // control plane (ECS / Aurora / SSM), never over the VPC, and the ALB invokes
+        // it through the Lambda API — not the network path.
+        const waker = new LambdaFunction(this, DEV_SUBSTRATE_WAKER_ID, {
+            runtime: Runtime.NODEJS_22_X,
+            handler: "index.handler",
+            code: Code.fromInline(source),
+            lambdaDescription: "Dev substrate slot waker",
+            roleDescription: "Execution role for the dev substrate slot waker",
+            timeout: DEV_SUBSTRATE_WAKER_TIMEOUT_SECONDS,
+            environment: { WAKER_SECRET_PARAM: wakerSecretParam },
+            inlinePolicy: [
+                new PolicyStatement({
+                    effect: Effect.ALLOW,
+                    actions: ["ssm:GetParameter"],
+                    resources: [
+                        `arn:${partition}:ssm:${region}:${account}:parameter${wakerSecretParam}`
+                    ]
+                }),
+                // Default-key SecureString: scope kms:Decrypt by ViaService, NOT by a CMK
+                // alias — the AWS-managed alias/aws/ssm never matches a per-app alias, so
+                // an alias-scoped grant would AccessDeny the decrypt (design VF4).
+                new PolicyStatement({
+                    effect: Effect.ALLOW,
+                    actions: ["kms:Decrypt"],
+                    resources: ["*"],
+                    conditions: {
+                        StringEquals: { "kms:ViaService": `ssm.${region}.amazonaws.com` }
+                    }
+                })
+            ]
+        });
+        // Standalone TG, NOT attached to the :80 listener — slot-ops wire it in per
+        // sleeping slot via the exported ARN (A7/§5.4), so the listener keeps its
+        // unmatched-host 404. Rationale + the auto ELB-invoke grant: lambdaAlbTarget.ts.
+        return createLambdaTargetGroup(this, DEV_SUBSTRATE_WAKER_TG_ID, {
+            handler: waker
+        });
+    }
+    #createDomain(props, loadBalancer) {
+        if (props.domain === undefined)
+            return {};
+        const { appDomain, parentDelegationRoleArn } = props.domain;
+        const childZoneName = `dev.${appDomain}`;
+        // The delegated child zone: createDelegationRole:false because the PARENT
+        // account owns the delegation role (this is the child). The HostedZone
+        // wrapper's create path auto-emits the `<zone>-nameservers` CFN export the
+        // parent consumes to point NS records at us — no manual export needed.
+        const childZone = new HostedZone(this, DEV_SUBSTRATE_ZONE_ID, {
+            zoneName: childZoneName,
+            createDelegationRole: false
+        });
+        // Case-1 same-org delegation fires only when a parent role ARN is supplied.
+        // The in-stack custom resource assumes the parent account's DelegationRole by
+        // LITERAL ARN (Role.fromRoleArn) — NOT Fn.importValue, which resolves
+        // same-account only and is exactly why the DomainDelegation pattern cannot go
+        // cross-account (design VD2-a). The parent DelegationRole trusts the whole
+        // org (OrganizationPrincipal), so a sibling dev account can assume it. Absent
+        // ARN ⇒ Case 2 (worker UPSERT, B3b) / Case 3 (manual), handled out of band:
+        // the zone + NS export above is all the substrate emits.
+        if (parentDelegationRoleArn !== undefined) {
+            const parentRole = Role.fromRoleArn(this, DEV_SUBSTRATE_PARENT_ROLE_ID, parentDelegationRoleArn);
+            new CrossAccountDelegationRecord(this, DEV_SUBSTRATE_DELEGATION_ID, {
+                delegationRole: parentRole,
+                delegatedZone: childZone.hostedZone,
+                delegatedZoneName: childZoneName,
+                parentHostedZoneName: appDomain
+            });
+        }
+        // Step 2 of the R2 two-step gate: synthesising the cert before the step-1 NS
+        // has propagated hangs ACM DNS-validation for hours, so "zone" stops here.
+        if ((props.phase ?? DEV_SUBSTRATE_DEFAULT_PHASE) !== "full")
+            return { devDomain: childZoneName };
+        // exportCertificateArn:false — consumed in-stack by the :443 listener (slots
+        // reference the exported LISTENER arn, not the cert), and the wildcard `*.`
+        // would otherwise render an invalid CFN export name.
+        const certificate = new DomainCertificate(this, DEV_SUBSTRATE_CERT_ID, {
+            domainName: `*.${childZoneName}`,
+            hostedZone: childZone.hostedZone,
+            exportCertificateArn: false
+        });
+        // Unconditional 404 as on :80 (per-slot rules attach out of band, §5.4). open
+        // (CDK default) adds the :443 ingress to the ALB SG.
+        const httpsListener = addRoutingListener(loadBalancer, DEV_SUBSTRATE_HTTPS_LISTENER_ID, { port: 443, certificate: certificate.certificate, default404: true });
+        return { devDomain: childZoneName, httpsListener };
+    }
+    /**
+     * Emit the substrate's cross-stack exports under a `FjallDev<App>DevSubstrate*`
+     * prefix. The scoped slot-ops role has no `ec2:Describe*` / discovery reach, so
+     * the hand-created G2 slot service consumes these to place tasks, register a
+     * host-header rule, inject DB creds and point a sleeping slot at the waker.
+     *
+     * No KMS-alias export: the substrate's Aurora + waker use the AWS-managed default
+     * key (design VF4 — the waker's kms:Decrypt is ViaService-scoped precisely
+     * because there is no per-app CMK), so there is no alias to export.
+     *
+     * The Aurora slot-SG ingress (A2.5) makes the Database stack depend on the
+     * Compute stack. So the two DB exports are scoped under `databaseScope` (the
+     * Database stack) — a Compute-stack output referencing a Database-stack ARN
+     * would invert that edge into a synth-fatal cycle. Every other export is a
+     * Compute-stack (or Compute→Network) same-direction ref and rides `this`.
+     */
+    #emitExports(databaseScope, values) {
+        const prefix = `${toPascalCase(this.app.getName())}DevSubstrate`;
+        const emit = (scope, key, value) => {
+            new CfnOutput(scope, `${prefix}${key}`, {
+                value,
+                exportName: `${prefix}${key}`
+            });
+        };
+        emit(this, "VpcId", values.vpcId);
+        // CFN exports are scalar — comma-join the subnet ids; the consumer splits.
+        emit(this, "PrivateSubnetIds", values.privateSubnetIds.join(","));
+        emit(this, "SlotSecurityGroupId", values.slotSecurityGroupId);
+        emit(this, "ClusterName", values.clusterName);
+        emit(this, "SlotListenerArn", values.slotListenerArn);
+        emit(this, "AlbCloudWatchName", values.albCloudWatchName);
+        emit(databaseScope, "DbClusterArn", values.dbClusterArn);
+        emit(databaseScope, "DbSecretArn", values.dbSecretArn);
+        emit(this, "SlotExecutionRoleArn", values.slotExecutionRoleArn);
+        emit(this, "SlotRepositoryUri", values.slotRepositoryUri);
+        emit(this, "WakerTargetGroupArn", values.wakerTargetGroupArn);
+        emit(this, "DatabaseMode", values.databaseMode);
+        if (values.devDomain !== undefined) {
+            emit(this, "DevDomain", values.devDomain);
+        }
+    }
+    #tagFenced(scope) {
+        Tags.of(scope).add(DEV_TAG_KEY, DEV_TAG_VALUE);
+        Tags.of(scope).add(DEV_APP_TAG_KEY, this.appId);
+    }
+}

package/dist/lib/patterns/aws/devSubstrate.waker.source.cjs

@@ -0,0 +1,13 @@
+"use strict";
+
+// Dev-substrate slot waker, invoked as an ALB Lambda target. Milestone
+// placeholder — the real wake-token check + ECS/Aurora resume land in §5.4.
+// ALB Lambda-target responses MUST carry all five fields; a missing
+// statusDescription or isBase64Encoded 502s at the ALB.
+exports.handler = async () => ({
+  statusCode: 200,
+  statusDescription: "200 OK",
+  isBase64Encoded: false,
+  headers: { "content-type": "text/plain; charset=utf-8" },
+  body: "Slot is warming up. Refresh in a moment."
+});

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

@@ -0,0 +1,17 @@
+import { ApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { type ISecurityGroup, type IVpc } from "aws-cdk-lib/aws-ec2";
+import type { Construct } from "constructs";
+export interface ApplicationLoadBalancerOptions {
+    readonly vpc: IVpc;
+    /** Public (internet-facing, PUBLIC subnets) vs internal (PRIVATE_WITH_EGRESS). */
+    readonly internetFacing: boolean;
+    readonly loadBalancerName?: string;
+    readonly securityGroup?: ISecurityGroup;
+}
+/**
+ * Context-free Application Load Balancer factory shared by the ECS cluster path
+ * and the dev substrate. Subnet placement is derived from `internetFacing`
+ * (PUBLIC when internet-facing, PRIVATE_WITH_EGRESS when internal) — matching the
+ * ECS path's existing derivation so the extraction is byte-identical.
+ */
+export declare function createApplicationLoadBalancer(scope: Construct, id: string, options: ApplicationLoadBalancerOptions): ApplicationLoadBalancer;

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

@@ -0,0 +1,23 @@
+import { ApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { SubnetType } from "aws-cdk-lib/aws-ec2";
+/**
+ * Context-free Application Load Balancer factory shared by the ECS cluster path
+ * and the dev substrate. Subnet placement is derived from `internetFacing`
+ * (PUBLIC when internet-facing, PRIVATE_WITH_EGRESS when internal) — matching the
+ * ECS path's existing derivation so the extraction is byte-identical.
+ */
+export function createApplicationLoadBalancer(scope, id, options) {
+    return new ApplicationLoadBalancer(scope, id, {
+        vpc: options.vpc,
+        internetFacing: options.internetFacing,
+        ...(options.securityGroup && { securityGroup: options.securityGroup }),
+        ...(options.loadBalancerName && {
+            loadBalancerName: options.loadBalancerName
+        }),
+        vpcSubnets: {
+            subnetType: options.internetFacing
+                ? SubnetType.PUBLIC
+                : SubnetType.PRIVATE_WITH_EGRESS
+        }
+    });
+}

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

@@ -7,6 +7,11 @@ export function getContainerImage(ctx, serviceName, containerConfig, serviceProp
     if (!imageSource) {
         return ContainerImage.fromRegistry(DEFAULT_ECS_FALLBACK_IMAGE);
     }
+    const entity = {
+        kind: "ecs-service",
+        declaredBy: serviceName,
+        docker: serviceProps.docker
+    };
     if (typeof imageSource === "string") {
         const isFullRegistryUrl = /^(docker\.io|registry\.hub\.docker\.com|ghcr\.io)\//i.test(imageSource) ||
             imageSource.startsWith("public.ecr.aws/") ||
@@ -14,11 +19,11 @@ export function getContainerImage(ctx, serviceName, containerConfig, serviceProp
         if (isFullRegistryUrl) {
             return ContainerImage.fromRegistry(imageSource);
         }
-        const param = getOrCreateImageTagParameter(ctx.scope, serviceName);
+        const param = getOrCreateImageTagParameter(ctx.scope, serviceName, entity);
         return ContainerImage.fromEcrRepository(Repository.fromRepositoryName(ctx.scope, `${serviceName}${containerConfig.name}EcrRepo`, imageSource), param.valueAsString);
     }
     if (imageSource instanceof Repository) {
-        const param = getOrCreateImageTagParameter(ctx.scope, serviceName);
+        const param = getOrCreateImageTagParameter(ctx.scope, serviceName, entity);
         return ContainerImage.fromEcrRepository(imageSource, param.valueAsString);
     }
     return imageSource;

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

@@ -1,4 +1,4 @@
-import { type ApplicationListener, ApplicationLoadBalancer, type IApplicationTargetGroup, ListenerCondition } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { type ApplicationListener, type ApplicationLoadBalancer, type IApplicationTargetGroup } from "aws-cdk-lib/aws-elasticloadbalancingv2";
 import { type ISecurityGroup } from "aws-cdk-lib/aws-ec2";
 import { type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
 import { ARecord, type IHostedZone } from "aws-cdk-lib/aws-route53";
@@ -6,15 +6,9 @@ import type { AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
 import type { ContainerDefinition, FargateService, Ec2Service } from "aws-cdk-lib/aws-ecs";
 import { SecurityGroup } from "../networking/securityGroup.js";
 import type { EcsConstructContext } from "./ecsContext.js";
-import type { EcsRoutingConfig, EcsServiceProps } from "./ecsTypes.js";
-/** Mutable priority state for ALB rule ordering. */
-export interface PriorityState {
-    nextPriority: number;
-    usedPriorities: Set<number>;
-}
-/** Returns the next unused auto-incremented ALB priority, skipping any manually assigned values. */
-export declare function getNextPriority(state: PriorityState): number;
-export declare function buildRoutingConditions(rule: EcsRoutingConfig | undefined): ListenerCondition[];
+import type { EcsServiceProps } from "./ecsTypes.js";
+import { type PriorityState } from "./hostHeaderListenerRule.js";
+export type { PriorityState } from "./hostHeaderListenerRule.js";
 export declare function addLoadBalancer(ctx: EcsConstructContext, anyServiceUsesEc2: boolean, asgSecurityGroup?: ISecurityGroup): {
     loadBalancer: ApplicationLoadBalancer;
     loadBalancerSecurityGroup?: SecurityGroup;