@fjall/components-infrastructure 37.0.0 → 39.0.0

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

@@ -95,8 +95,13 @@ export class Buildkite extends Construct {
             appBackupTier
         });
         // Secrets (SSH deploy keys, git credentials) must survive stack teardown
-        // and accidental overwrite.
-        const managedSecretsBucket = new S3Bucket(this, `${id}ManagedSecretsBucket`, { versioned: true, removalPolicy: RemovalPolicy.RETAIN });
+        // and accidental overwrite — which is exactly what a backup plan is for,
+        // so the bucket takes the app's tier like the artefact bucket above.
+        const managedSecretsBucket = new S3Bucket(this, `${id}ManagedSecretsBucket`, {
+            versioned: true,
+            removalPolicy: RemovalPolicy.RETAIN,
+            appBackupTier
+        });
         if (fjallApiKeyParameterName !== undefined ||
             pipelineSecretsPrefix !== undefined) {
             this.addAgentSecretsEnvHook(id, managedSecretsBucket, {

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

@@ -4,7 +4,7 @@ import { type IApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalanc
 import { type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
 import { type ICachePolicy, type IResponseHeadersPolicy } from "aws-cdk-lib/aws-cloudfront";
 import type App from "../../app.js";
-import { CloudFrontDistribution, type CachePolicyPreset, type AccessGateConfig } from "../../resources/aws/cdn/index.js";
+import { CloudFrontDistribution, type CloudFrontLogFormat, type CachePolicyPreset, type AccessGateConfig } from "../../resources/aws/cdn/index.js";
 import { type ICdn } from "./interfaces/cdn.js";
 import { type StaticSiteRouting, type CloudFrontPriceClass } from "@fjall/util";
 import { type BackupTier } from "../../utils/backupTierMapping.js";
@@ -83,17 +83,17 @@ interface BaseCdnProps {
     certificateArn?: string;
     comment?: string;
     /**
-     * Standard (S3) access logging. Default: the app backup tier's
-     * `cloudFrontLogging` column — enterprise logs to the stack's shared,
-     * lifecycle-expired access-log bucket under `cloudfront/<id>/`. Set either
-     * knob to take over: `enableLogging: false` opts out at any tier,
-     * `logBucket` delivers to a bucket of your own. Standard logging cannot
-     * deliver into an opt-in region, so a tier- or explicitly-enabled CDN whose
-     * delivery region is opt-in is refused at synth with those two cures — see
-     * {@link CloudFrontDistributionProps.enableLogging}.
+     * Standard logging (v2): access logs delivered through CloudWatch Logs.
+     * Default: the app backup tier's `cloudFrontLogging` column — enterprise
+     * logs to the stack's shared, lifecycle-expired access-log bucket under
+     * `cloudfront/<id>`, as JSON. An object takes over at any tier (its
+     * `bucket`, `prefix` and `format` each default as above); `false` opts
+     * out at any tier. The delivery resources live in the CDN stack when the
+     * app deploys to us-east-1 and in the app's `UsEast1CdnLogging` stack
+     * otherwise (CloudWatch Logs accepts them there only), so a logging CDN
+     * outside us-east-1 needs the `App` — the factory path fills it.
      */
-    enableLogging?: boolean;
-    logBucket?: IBucket;
+    logging?: CdnLoggingConfig | false;
     priceClass?: CloudFrontPriceClass;
     forwardHostHeader?: boolean;
     accessGate?: false | AccessGateConfig;
@@ -104,6 +104,14 @@ interface BaseCdnProps {
      */
     appBackupTier?: BackupTier;
 }
+export interface CdnLoggingConfig {
+    /** Bucket the logs land in; defaults to the stack's access-log bucket. */
+    bucket?: IBucket;
+    /** Key prefix (no leading or trailing slash); defaults to `cloudfront/<id>`. */
+    prefix?: string;
+    /** CloudWatch Logs output format; defaults to `json`. */
+    format?: CloudFrontLogFormat;
+}
 /**
  * S3 origin CDN props - use with S3 bucket
  */

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

@@ -1,7 +1,7 @@
-import { Fn, Token } from "aws-cdk-lib";
+import { Fn, Stack, Token } from "aws-cdk-lib";
 import { Certificate } from "aws-cdk-lib/aws-certificatemanager";
 import { CloudFrontTarget, LoadBalancerTarget } from "aws-cdk-lib/aws-route53-targets";
-import { CloudFrontDistribution } from "../../resources/aws/cdn/index.js";
+import { assertNoLegacyLoggingProps, CLOUDFRONT_LOG_DELIVERY_REGION, CloudFrontDistribution } from "../../resources/aws/cdn/index.js";
 import { AliasRecord } from "../../resources/aws/networking/index.js";
 import { tierDefault } from "../../utils/backupTierMapping.js";
 import { stackAccessLogBucket } from "../../resources/aws/logging/index.js";
@@ -12,31 +12,54 @@ import { isStorage } from "./storage.js";
 import { CdnEcsOriginResolver, cdnOriginRefusal, internalAlbMessage, normaliseDnsName } from "./cdnAppOrigin.js";
 import { isCompute, isEcsCompute, isLambdaCompute } from "./compute.js";
 /**
- * An explicit `enableLogging` or `logBucket` is the override and passes
- * through untouched; otherwise the tier decides, and a tier-enabled CDN logs
- * to the stack's shared access-log bucket under its own prefix.
+ * `false` is off at any tier; an object is on at any tier with its own
+ * defaults filled; `undefined` lets the tier decide, and a tier-enabled CDN
+ * logs to the stack's shared access-log bucket under its own prefix.
  */
 function resolveCdnLogging(scope, id, props) {
-    if (props.enableLogging !== undefined || props.logBucket !== undefined) {
-        return {
-            enableLogging: props.enableLogging,
-            logBucket: props.logBucket,
-            logFilePrefix: undefined
-        };
-    }
-    if (!tierDefault(props.appBackupTier, "cloudFrontLogging")) {
-        return {
-            enableLogging: undefined,
-            logBucket: undefined,
-            logFilePrefix: undefined
-        };
+    if (props.logging === false)
+        return undefined;
+    if (props.logging === undefined &&
+        !tierDefault(props.appBackupTier, "cloudFrontLogging")) {
+        return undefined;
     }
+    const config = props.logging ?? {};
     return {
-        enableLogging: true,
-        logBucket: stackAccessLogBucket(scope),
-        logFilePrefix: `cloudfront/${id}/`
+        bucket: config.bucket ?? stackAccessLogBucket(scope),
+        ...(config.prefix !== undefined && { prefix: config.prefix }),
+        ...(config.format !== undefined && { format: config.format }),
+        ...resolveLogDeliveryScope(scope, id, props.app)
     };
 }
+/**
+ * CloudWatch Logs accepts CloudFront delivery resources in us-east-1 only.
+ * A CDN stack already there hosts them itself; any other region hands them
+ * to the app's `UsEast1CdnLogging` stack, whose distribution and bucket
+ * ARNs arrive through CDK cross-region references — which need both stacks
+ * env-pinned, so a token region is refused here with the cure rather than
+ * by CloudFormation with a region error after the CDN stack has deployed.
+ */
+function resolveLogDeliveryScope(scope, id, app) {
+    const region = Stack.of(scope).region;
+    if (Token.isUnresolved(region)) {
+        throw new Error(`CDN '${id}': standard logging (v2) needs a concrete region at synth ` +
+            "— the delivery resources go to us-east-1 and reach the " +
+            "distribution through cross-region references, which resolve only " +
+            "between env-pinned stacks — but this stack's region is a token. " +
+            "Deploy through the Fjall CLI, or export CDK_DEFAULT_ACCOUNT and " +
+            "CDK_DEFAULT_REGION before synthesising; or set logging: false.");
+    }
+    if (region === CLOUDFRONT_LOG_DELIVERY_REGION)
+        return {};
+    if (app === undefined) {
+        throw new Error(`CDN '${id}': standard logging (v2) from region ${region} places its ` +
+            "delivery resources in the app's us-east-1 logging stack, but 'app' " +
+            "is unset. Create the CDN through the factory path — " +
+            "app.addCdn(CdnFactory.build(...)) — which fills it, pass 'app' " +
+            "explicitly, or set logging: false.");
+    }
+    return { deliveryScope: app.getUsEast1CdnLoggingStack().getStack() };
+}
 /**
  * The distribution's own alias names, normalised — consumed by the
  * origin-loop guard and by the ECS origin resolver (auto-resolution excludes
@@ -59,7 +82,10 @@ function collectAliasNames(props) {
  * Validates CDN props — synth-time hard errors for shapes CloudFormation
  * would only reject at deploy.
  */
-function validateCdnProps(props) {
+function validateCdnProps(id, props) {
+    // The pattern rebuilds the distribution props field by field, so the
+    // resource-layer refusal never sees a legacy key given here.
+    assertNoLegacyLoggingProps(`CDN '${id}'`, props, "logging: { bucket?, prefix?, format? } | false");
     const hasCertificate = !!(props.certificate || props.certificateArn);
     // domainConfig is the managed-domain authority for the viewer config —
     // mixing it with the literal surface would give the alias list and the
@@ -251,7 +277,7 @@ const ROUTING_CDN_BEHAVIOUR = {
 };
 export class Cdn extends CloudFrontDistribution {
     constructor(scope, id, props) {
-        validateCdnProps(props);
+        validateCdnProps(id, props);
         // Zone + certificate resolve BEFORE super() — the viewer certificate is
         // part of the distribution's props — so their constructs land on the CDN
         // stack (`scope`) under `${id}`-prefixed IDs, the pattern convention.
@@ -476,6 +502,7 @@ export class Cdn extends CloudFrontDistribution {
                 originRequestPolicy: props.originRequestPolicy
             }
             : {};
+        const logging = resolveCdnLogging(scope, id, props);
         return {
             distributionProps: {
                 appName,
@@ -486,7 +513,7 @@ export class Cdn extends CloudFrontDistribution {
                 domainNames,
                 certificate,
                 comment: props.comment,
-                ...resolveCdnLogging(scope, id, props),
+                ...(logging !== undefined && { logging }),
                 priceClass: props.priceClass,
                 forwardHostHeader: props.forwardHostHeader ?? impliedForwardHostHeader,
                 accessGate: props.accessGate,
@@ -699,7 +726,8 @@ export class CdnFactory {
             // The App is the only place the app name is known here; without it the
             // export falls back to the construct id and the Domain import misses.
             // The App instance itself rides along for domainConfig resolution
-            // (certificate placement needs app.getUsEast1CertificateStack()).
+            // (certificate placement needs app.getUsEast1CertificateStack()) and
+            // for log-delivery placement (app.getUsEast1CdnLoggingStack()).
             return new Cdn(scope, id, {
                 ...props,
                 appName: props.appName ?? app.getName(),

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

@@ -367,6 +367,9 @@ export class ClickHouseDatabase extends Construct {
         const backupBucket = props.backupBucket ??
             new S3Bucket(this, "ClickHouseBackupBucket", {
                 versioned: true,
+                ...(props.appBackupTier !== undefined && {
+                    appBackupTier: props.appBackupTier
+                }),
                 lifecycleRules: [
                     {
                         enabled: true,
@@ -525,8 +528,7 @@ export class ClickHouseDatabase extends Construct {
                     `${sidecarTlsPreamble}${optimisePreamble}\n${optimiseScript}`
                 ],
                 secrets: maintenanceSecrets,
-                logGroup: optimiseTaskLogGroup,
-                securityGroups: [securityGroup]
+                logGroup: optimiseTaskLogGroup
             });
             maintenanceLogGroups.push({
                 job: "optimise",
@@ -555,8 +557,7 @@ export class ClickHouseDatabase extends Construct {
                     })}`
                 ],
                 secrets: maintenanceSecrets,
-                logGroup: backupTaskLogGroup,
-                securityGroups: [securityGroup]
+                logGroup: backupTaskLogGroup
             });
             maintenanceLogGroups.push({
                 job: "backup",
@@ -590,6 +591,9 @@ export class ClickHouseDatabase extends Construct {
             ...(props.appBackupTier !== undefined && {
                 appBackupTier: props.appBackupTier
             }),
+            // ClickHouse is infrastructure: the deploy engine must never roll it
+            // out, restart it or rebind it as one of the app's own services.
+            deployableServices: false,
             cluster: {
                 loadBalancer: false,
                 securityGroup,

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

@@ -1,4 +1,4 @@
-import { AwsLogDriver, ContainerImage, DeploymentLifecycleStage, Secret as EcsSecret } from "aws-cdk-lib/aws-ecs";
+import { AwsLogDriver, ContainerImage, DeploymentLifecycleStage, NetworkMode, Secret as EcsSecret } from "aws-cdk-lib/aws-ecs";
 import { Peer, Port, SubnetType } from "aws-cdk-lib/aws-ec2";
 import { Effect, PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
 import { Annotations, Aws, Stack, Token } from "aws-cdk-lib";
@@ -269,6 +269,21 @@ export function validateEcsProps(props) {
                 "does not own. Either omit cluster.securityGroup (a Fjall-owned SG will be created) or set directAccess: false.");
         }
     }
+    for (const entry of props.cluster?.scheduledTasks ?? []) {
+        if (entry.networkMode === NetworkMode.AWS_VPC) {
+            throw new Error(`Scheduled task '${entry.name}': networkMode AWS_VPC is not supported for scheduled tasks — ` +
+                "a scheduled task's connections are wired to the cluster's EC2 capacity security groups " +
+                "(EcsCluster.getEc2CapacityConnectable), which an awsvpc task's own ENI does not wear, so every " +
+                "connection grant would be unreachable at runtime with nothing failing at synth. Remove networkMode " +
+                "to run on the instance ENI, or set NetworkMode.HOST. Govern the task's reachability with the " +
+                "cluster-level securityGroup on EcsClusterConfig.");
+        }
+        if (entry.logGroup !== undefined && entry.logRetention !== undefined) {
+            throw new Error(`Scheduled task '${entry.name}': "logGroup" and "logRetention" are mutually exclusive on ` +
+                "EcsScheduledTaskConfig — the supplied logGroup owns its own retention, so logRetention " +
+                `(${entry.logRetention}) would be silently discarded. Supply one or the other, not both.`);
+        }
+    }
 }
 const DEFAULT_MIGRATE_CONTAINER_NAME = "migrate";
 /**
@@ -976,6 +991,7 @@ export class EcsCompute extends Construct {
             applicationId: props.applicationId ??
                 (App.hasInstance() ? App.getInstance().getName() : undefined),
             ...(props.taskStopWatchdog === false && { taskStopWatchdog: false }),
+            ...(props.deployableServices === false && { deployableServices: false }),
             ...(props.containerInsights !== undefined && {
                 containerInsights: props.containerInsights
             }),

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

@@ -1,6 +1,6 @@
 import { type Repository } from "aws-cdk-lib/aws-ecr";
 import { type RepositoryImage, type ContainerImage, type PortMapping, type Secret as EcsSecret, type NetworkMode } from "aws-cdk-lib/aws-ecs";
-import { type IPeer, type ISecurityGroup, type IVpc, type Port, type SubnetSelection } from "aws-cdk-lib/aws-ec2";
+import { type IPeer, type ISecurityGroup, type IVpc, type Port } from "aws-cdk-lib/aws-ec2";
 import { type ILogGroup, type RetentionDays } from "aws-cdk-lib/aws-logs";
 import { type PolicyDocument, type IManagedPolicy, type PolicyStatement } from "aws-cdk-lib/aws-iam";
 import type { ITopic } from "aws-cdk-lib/aws-sns";
@@ -554,7 +554,8 @@ export interface EcsScheduledTaskConfig {
      * Connections to data resources — the same connector interface services
      * use. Produces IAM grants on the task role, security-group wiring (via the
      * cluster's EC2 capacity security group — scheduled tasks run on the
-     * cluster's instances), and schema-version gate env injection when a
+     * cluster's instances, which is why `networkMode: AWS_VPC` is refused
+     * here), and schema-version gate env injection when a
      * connected database declares `migrations:`. Scheduled tasks never
      * materialise a `fjall-schema-gate` container; only the env is injected —
      * the task's own entrypoint decides whether to gate on it.
@@ -576,8 +577,18 @@ export interface EcsScheduledTaskConfig {
      * removal default (D17).
      */
     logRetention?: RetentionDays;
-    securityGroups?: ISecurityGroup[];
-    subnetSelection?: SubnetSelection;
+    /**
+     * Task network mode. Omit for the `Ec2TaskDefinition` default (BRIDGE, as
+     * measured on aws-cdk-lib 2.265.0 — the caret range can move it); `HOST` is
+     * permitted.
+     *
+     * `AWS_VPC` is REFUSED at synth. A scheduled task's `connections` are wired
+     * onto the cluster's EC2 capacity security groups
+     * (`EcsCluster.getEc2CapacityConnectable`), which an awsvpc task's own ENI
+     * does not wear — every grant would land and every network path would not,
+     * with nothing failing at synth. Govern reachability with the cluster-level
+     * `securityGroup` on `EcsClusterConfig` instead.
+     */
     networkMode?: NetworkMode;
     /** Host-bind volumes mounted into the task's container. */
     volumes?: ContainerVolume[];
@@ -641,6 +652,10 @@ export interface EcsClusterConfig {
      * Scheduled tasks materialised into `Ec2TaskDefinition`s and registered via
      * `app.addSchedule(...)` against the existing `EcsScheduleTarget` shape
      * ({ ecs, serviceName, taskCount }). See AC34.
+     *
+     * These run on the cluster's own EC2 instances and share their network
+     * interface, so `networkMode: AWS_VPC` is refused per entry — see
+     * {@link EcsScheduledTaskConfig.networkMode}.
      */
     scheduledTasks?: EcsScheduledTaskConfig[];
 }
@@ -1081,6 +1096,17 @@ export interface EcsComputeProps {
      * opt-out for cost-sensitive clusters.
      */
     taskStopWatchdog?: false;
+    /**
+     * Deployable-service exports (default on): one `DeployableService` output
+     * per service plus the cluster's `DeployableCluster` and `ClusterArn`
+     * outputs, named by `@fjall/util`'s `stackExportNames` builders. The
+     * deploy engine's `EcsServiceResolver` reads the app's Compute stack
+     * outputs to find the ECS services that `fjall services`, `fjall rollout`,
+     * `fjall restart`, a code-only deploy and a rollback act on. `false` opts
+     * out a cluster hosting an infrastructure service, so the resolver never
+     * binds it as an app service.
+     */
+    deployableServices?: false;
     /**
      * CloudWatch Container Insights (default off). Enabling it bills
      * ~$0.30/metric-month of custom `ECS/ContainerInsights` metrics per cluster

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

@@ -19,6 +19,7 @@ const COMPUTE_PROP_APPLICABILITY = {
     alertsTopic: ["ecs"],
     applicationId: ["ecs"],
     taskStopWatchdog: ["ecs"],
+    deployableServices: ["ecs"],
     containerInsights: ["ecs"],
     deployment: ["lambda"],
     functionUrl: ["lambda"],

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

@@ -99,9 +99,9 @@ export class Domain extends Construct {
         }
     }
     /**
-     * Re-publish the domain's effective zone name under a predictable export
-     * key so downstream consumers (Phase 2, Phase 3 eject) can resolve the
-     * managed zone without knowing the registrar discriminant. The `Zone` and
+     * Re-publish the domain's effective zone name under a predictable output
+     * key (mirrored byte-for-byte by the eject template) so a stack reader can
+     * name the zone without knowing the registrar discriminant. The `Zone` and
      * `HostedZoneId` outputs on the inner `HostedZone` construct cover the
      * Route53-backed paths; this output covers external-records mode where no
      * hosted zone exists.

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

@@ -7,12 +7,15 @@ export interface ExternalRecordsPatternResult {
 }
 /**
  * Composition for `registrar: "external-records"`. No Route53 hosted zone is
- * created; certificates still use ACM DNS validation (the user must paste the
- * validation records at their external registrar) and any user-declared
- * records are emitted as `ManualRecord` entries with per-record `CfnOutput`s
- * so Phase 2 can resolve token values after deploy.
+ * created. Certificates use ACM DNS validation with no zone to write to, so
+ * their validation CNAMEs must be created at the external registrar — and
+ * those records do not exist at synth: ACM chooses them when CloudFormation
+ * creates the certificate, and `AWS::CertificateManager::Certificate`
+ * returns only its ARN. They are therefore never `ManualRecord` entries:
+ * they are read from ACM (`DescribeCertificate`) once the certificate is
+ * pending, while CloudFormation waits for the records to resolve.
  *
- * Ordering invariant: certificate-validation entries come first so the user
- * adds them before the app records (ACM can't issue until validation resolves).
+ * User-declared records become `ManualRecord` entries, each with a
+ * `CfnOutput` triple keyed by its position in `records`.
  */
 export declare function composeExternalRecords(scope: Construct, props: ExternalRecordsProps): ExternalRecordsPatternResult;

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

@@ -6,58 +6,35 @@ import { resolveRecordFqdn } from "../../utils/domainTypes.js";
 const MANUAL_RECORD_TTL_SECONDS = 300;
 /**
  * Composition for `registrar: "external-records"`. No Route53 hosted zone is
- * created; certificates still use ACM DNS validation (the user must paste the
- * validation records at their external registrar) and any user-declared
- * records are emitted as `ManualRecord` entries with per-record `CfnOutput`s
- * so Phase 2 can resolve token values after deploy.
+ * created. Certificates use ACM DNS validation with no zone to write to, so
+ * their validation CNAMEs must be created at the external registrar — and
+ * those records do not exist at synth: ACM chooses them when CloudFormation
+ * creates the certificate, and `AWS::CertificateManager::Certificate`
+ * returns only its ARN. They are therefore never `ManualRecord` entries:
+ * they are read from ACM (`DescribeCertificate`) once the certificate is
+ * pending, while CloudFormation waits for the records to resolve.
  *
- * Ordering invariant: certificate-validation entries come first so the user
- * adds them before the app records (ACM can't issue until validation resolves).
+ * User-declared records become `ManualRecord` entries, each with a
+ * `CfnOutput` triple keyed by its position in `records`.
  */
 export function composeExternalRecords(scope, props) {
     const safeZone = toPascalCase(getSafeZoneName(props.zoneName));
     const certificates = new Map();
     const manualRecords = [];
-    // 1. Certificates — ACM DNS validation emits CNAMEs the user must paste at
-    //    their registrar. Capture the validation records as ManualRecord
-    //    entries (cert-validation first per ordering invariant).
     const normalisedCerts = (props.certificates ?? []).map(normaliseCertificate);
     normalisedCerts.forEach((cert, index) => {
         const safeCertName = toPascalCase(cert.domainName.split(".").join(""));
         const acm = new AcmCertificate(scope, `${safeZone}${safeCertName}Cert${index}`, {
             domainName: cert.domainName,
             subjectAlternativeNames: cert.subjectAlternativeNames,
-            // No hosted zone to validate against — ACM emits tokens for the user
-            // to resolve via `describeStackResources` or deploy output.
             validation: CertificateValidation.fromDns(),
             transparencyLoggingEnabled: cert.transparencyLogging ?? true
         });
         certificates.set(cert.domainName, acm);
-        const certNames = [
-            cert.domainName,
-            ...(cert.subjectAlternativeNames ?? [])
-        ];
-        certNames.forEach((name, nameIndex) => {
-            // `domainValidationOption` returns a token CNAME name/value pair. Using
-            // `attrDomainValidationOptions` returns an array token; per-name lookup
-            // uses index. CDK exposes the first validation option via
-            // `certificate.certificateArn` only — we fall back to emitting a
-            // predictable CfnOutput pointing to the attribute for Phase 2.
-            const record = {
-                name: `_acme-challenge.${name}`,
-                type: "CNAME",
-                value: `<ACM-validation-token-for-${name}>`,
-                ttl: MANUAL_RECORD_TTL_SECONDS,
-                reason: "certificate-validation"
-            };
-            manualRecords.push(record);
-            emitManualRecordOutputs(scope, safeZone, manualRecords.length - 1, record, `CertValidation${safeCertName}${nameIndex}`);
-        });
     });
-    // 2. User-declared records. Typed targets resolve to token strings via
-    //    `resolveTargetToDnsName`. Apex ALIAS was already rejected by
-    //    `validateDomainProps`, so all records here are safe to emit as manual
-    //    entries.
+    // Typed targets resolve to token strings via `resolveTargetToDnsName`.
+    // Apex ALIAS was already rejected by `validateDomainProps`, so all records
+    // here are safe to emit as manual entries.
     const records = props.records ?? [];
     records.forEach((record, index) => {
         const fqdn = resolveRecordFqdn(record.name, props.zoneName);
@@ -67,11 +44,10 @@ export function composeExternalRecords(scope, props) {
                 name: fqdn,
                 type: "CNAME",
                 value,
-                ttl: MANUAL_RECORD_TTL_SECONDS,
-                reason: "user-declared"
+                ttl: MANUAL_RECORD_TTL_SECONDS
             };
             manualRecords.push(manual);
-            emitManualRecordOutputs(scope, safeZone, manualRecords.length - 1, manual, `UserRecord${index}`);
+            emitManualRecordOutputs(scope, safeZone, index, manual);
             return;
         }
         const rawValue = record.value;
@@ -80,11 +56,10 @@ export function composeExternalRecords(scope, props) {
             name: fqdn,
             type: narrowManualType(record.type),
             value: joined,
-            ttl: record.ttl ?? MANUAL_RECORD_TTL_SECONDS,
-            reason: "user-declared"
+            ttl: record.ttl ?? MANUAL_RECORD_TTL_SECONDS
         };
         manualRecords.push(manual);
-        emitManualRecordOutputs(scope, safeZone, manualRecords.length - 1, manual, `UserRecord${index}`);
+        emitManualRecordOutputs(scope, safeZone, index, manual);
     });
     return { certificates, manualRecords };
 }
@@ -115,17 +90,18 @@ function narrowManualType(type) {
             return "TXT";
     }
 }
-function emitManualRecordOutputs(scope, safeZone, index, record, discriminator) {
-    new CfnOutput(scope, `${safeZone}ManualRecord${discriminator}Name`, {
+function emitManualRecordOutputs(scope, safeZone, index, record) {
+    const idPrefix = `${safeZone}ManualRecordUserRecord${index}`;
+    new CfnOutput(scope, `${idPrefix}Name`, {
         key: `${safeZone}ManualRecord${index}Name`,
         value: record.name,
-        description: `External-records manual DNS entry (${record.reason})`
+        description: "External-records manual DNS entry (user-declared)"
     });
-    new CfnOutput(scope, `${safeZone}ManualRecord${discriminator}Type`, {
+    new CfnOutput(scope, `${idPrefix}Type`, {
         key: `${safeZone}ManualRecord${index}Type`,
         value: record.type
     });
-    new CfnOutput(scope, `${safeZone}ManualRecord${discriminator}Value`, {
+    new CfnOutput(scope, `${idPrefix}Value`, {
         key: `${safeZone}ManualRecord${index}Value`,
         value: record.value
     });

package/dist/lib/patterns/aws/interfaces/domain.d.ts

@@ -158,15 +158,18 @@ export interface ExternalRecordsProps extends DomainCommonProps {
 }
 export type DomainProps = Route53ApexProps | ExternalDelegatedProps | ExternalRecordsProps;
 /**
- * Manual record emitted by `registrar: "external-records"` mode for the user
- * to paste at their external registrar. For typed targets the `value` is a
- * CloudFormation token (`Fn::ImportValue`) at synth time; Phase 2 resolves the
- * concrete value via `describeStackResources` after deploy.
+ * A user-declared record that `registrar: "external-records"` mode reports
+ * for the user to create at their external registrar, one per `records`
+ * entry, in declaration order. For typed targets the `value` is a
+ * CloudFormation token (`Fn::ImportValue`) at synth time; the concrete host
+ * is the deployed stack's `ManualRecord<index>Value` output.
+ *
+ * Certificate-validation records are never manual records: ACM chooses them
+ * at deploy time, so no synth-time value exists (see `composeExternalRecords`).
  */
 export interface ManualRecord {
     readonly name: string;
     readonly type: "A" | "AAAA" | "CNAME" | "TXT";
     readonly value: string;
     readonly ttl: number;
-    readonly reason: "certificate-validation" | "user-declared";
 }

package/dist/lib/patterns/aws/interfaces/pattern.d.ts

@@ -18,6 +18,7 @@ import { type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
 import { type Duration } from "aws-cdk-lib";
 import { type Construct } from "constructs";
 import type { HstsConfig } from "../../../resources/aws/cdn/responseHeadersPolicy.js";
+import type { OpenNextBucketKey } from "@fjall/util/patterns";
 import { type RelationalDatabase, type DynamoDBDatabase, type ProxyConfig, type ReadReplicaConfig, type CredentialsConfig, type EncryptionConfig, type AuroraEncryptionConfig, type AuroraWriterConfig, type AuroraReadersConfig, type DatabaseInsightsConfig } from "../database.js";
 import { type LambdaCompute } from "../compute.js";
 import { type Storage } from "../storage.js";
@@ -210,22 +211,20 @@ export interface PatternStorageBucketConfig {
     versioned?: boolean;
 }
 /**
- * Full storage configuration for patterns.
- * Allows per-bucket configuration for each S3 bucket in the pattern.
+ * Full storage configuration for patterns: one optional entry per bucket
+ * the OpenNext construct builds — `assets` (static files), `cache` (the ISR
+ * cache) and `media` (uploads) — keyed by `OPENNEXT_BUCKET_KEYS` in
+ * `@fjall/util/patterns`, the vocabulary the generator's config schema is
+ * pinned to as well.
  *
  * @example
  * storage: {
  *   media: { versioned: true } // force on below the resilient tier
  * }
  */
-export interface PayloadStorageConfig {
-    /** Assets bucket (static files) */
-    assets?: PatternStorageBucketConfig;
-    /** Cache bucket (ISR cache) */
-    cache?: PatternStorageBucketConfig;
-    /** Media bucket (uploads) */
-    media?: PatternStorageBucketConfig;
-}
+export type PayloadStorageConfig = {
+    [Bucket in OpenNextBucketKey]?: PatternStorageBucketConfig;
+};
 /**
  * SQS queue configuration for pattern messaging.
  */

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

@@ -28,6 +28,16 @@ export interface IQueueProps {
         maxReceiveCount?: number;
     };
     encryption?: "SSE_SQS" | "SSE_KMS" | "NONE";
+    /**
+     * ARN of a customer-managed KMS key to encrypt the queue (and its
+     * auto-created DLQ) with. Requires `encryption: "SSE_KMS"` — the resource
+     * layer refuses the pair rather than ignoring the key. Absent with
+     * `"SSE_KMS"`, the queue takes the stack's shared key.
+     *
+     * An ARN rather than an `IKey` because this is the plan vocabulary the
+     * scaffold and the codemod write, the same as `S3Props.kmsKeyArn`; a key
+     * you hold in `infrastructure.ts` passes as `key.keyArn`.
+     */
     kmsKeyArn?: string;
     contentBasedDeduplication?: boolean;
     fifoThroughputLimit?: "perQueue" | "perMessageGroupId";

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

@@ -1,3 +1,4 @@
+import { Key } from "aws-cdk-lib/aws-kms";
 import { EventBus as CdkEventBus } from "aws-cdk-lib/aws-events";
 import { SQSQueue, SQS_LIMITS } from "../../resources/aws/messaging/sqs.js";
 import { SNSTopic } from "../../resources/aws/messaging/sns.js";
@@ -49,11 +50,10 @@ function validateSQSProps(props) {
                 "This setting will be ignored for standard queues.");
         }
     }
-    // Validate KMS encryption
-    if (props.kmsKeyArn && props.encryption !== "SSE_KMS") {
-        FjallLogger.warn("'kmsKeyArn' provided but 'encryption' is not SSE_KMS. " +
-            "The KMS key will be ignored.");
-    }
+    // `kmsKeyArn` beside a non-KMS encryption used to warn here and then be
+    // ignored. `SQSQueue` refuses it instead — a warning that the queue is
+    // about to discard the key it was handed is not a gate, and the refusal
+    // states both cures.
 }
 /**
  * Validates SNS Topic props.
@@ -85,7 +85,11 @@ export class QueueMessaging extends SQSQueue {
             deliveryDelay: props.deliveryDelay,
             deadLetterQueue: props.deadLetterQueue,
             encryption: props.encryption,
-            kmsKeyArn: props.kmsKeyArn,
+            // Resolved in the parent scope for the same reason `alertsTopic` is:
+            // `this` does not exist before super().
+            masterKey: props.kmsKeyArn === undefined
+                ? undefined
+                : Key.fromKeyArn(scope, `${id}KmsKey`, props.kmsKeyArn),
             contentBasedDeduplication: props.contentBasedDeduplication,
             fifoThroughputLimit: props.fifoThroughputLimit,
             deduplicationScope: props.deduplicationScope,