@fjall/components-infrastructure 0.96.0 → 0.99.1

package/dist/lib/resources/aws/monitoring/clickhouseAlarms.js

@@ -0,0 +1,139 @@
+import { Duration } from "aws-cdk-lib";
+import { Alarm, ComparisonOperator, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+import { SnsAction } from "aws-cdk-lib/aws-cloudwatch-actions";
+import { Metric } from "aws-cdk-lib/aws-cloudwatch";
+import { FilterPattern, MetricFilter } from "aws-cdk-lib/aws-logs";
+import { ALARM_DEFAULTS, registerAlarm, buildAlarmDescription } from "./alarmDefaults.js";
+const CLICKHOUSE_METRIC_NAMESPACE = "Fjall/ClickHouse";
+/**
+ * Single-node ClickHouse posture alarms. Covers host-level CPU + (optional)
+ * memory and disk via the CloudWatch Agent metric namespace `CWAgent`, plus
+ * two log-driven alarms:
+ *
+ * - **Stuck merges** — `client.ts` polls `system.merges` every 5 min and logs
+ *   `serverLogger.warn("ClickHouse", "Stuck merge detected")` when elapsed
+ *   exceeds 30 min. The metric filter on the webapp log group emits a count
+ *   metric per match; the alarm fires on Sum >= 1 over 5 min × 2 evaluations.
+ * - **Backup failures** — `AccessDenied` or `S3Exception` from the backup
+ *   task's BACKUP DATABASE TO S3 statement. Closes the silent-failure mode
+ *   that masked the original IAM-grant misconfiguration (see
+ *   `designs/2026-04-27-clickhouse-backup-iam-role.md`).
+ */
+export function createClickHouseAlarms(props) {
+    const { scope, instanceRole, asgName, alarmTopic, webappLogGroup, backupTaskLogGroup, config = {} } = props;
+    const alarms = [];
+    const snsAction = new SnsAction(alarmTopic);
+    const cpuAlarm = new Alarm(scope, "ClickHouseCpuAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse host CPU utilisation exceeds threshold", undefined),
+        metric: new Metric({
+            namespace: "AWS/EC2",
+            metricName: "CPUUtilization",
+            dimensionsMap: { AutoScalingGroupName: asgName },
+            period: ALARM_DEFAULTS.EVALUATION_PERIOD,
+            statistic: "Average"
+        }),
+        threshold: config.cpuThreshold ?? 90,
+        evaluationPeriods: 3,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(cpuAlarm, snsAction, alarms);
+    const memoryAlarm = new Alarm(scope, "ClickHouseMemoryAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse host memory utilisation exceeds threshold (CWAgent)", undefined),
+        metric: new Metric({
+            namespace: "CWAgent",
+            metricName: "mem_used_percent",
+            dimensionsMap: { AutoScalingGroupName: asgName },
+            period: ALARM_DEFAULTS.EVALUATION_PERIOD,
+            statistic: "Average"
+        }),
+        threshold: config.memoryThreshold ?? 80,
+        evaluationPeriods: 3,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(memoryAlarm, snsAction, alarms);
+    const diskWarnAlarm = new Alarm(scope, "ClickHouseDiskWarnAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse data volume above 70% used — plan growth response", undefined),
+        metric: new Metric({
+            namespace: "CWAgent",
+            metricName: "disk_used_percent",
+            dimensionsMap: { AutoScalingGroupName: asgName },
+            period: Duration.minutes(15),
+            statistic: "Average"
+        }),
+        threshold: config.diskWarnThreshold ?? 70,
+        evaluationPeriods: 2,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(diskWarnAlarm, snsAction, alarms);
+    const diskCriticalAlarm = new Alarm(scope, "ClickHouseDiskCriticalAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse data volume above 85% used — imminent insert failures", undefined),
+        metric: new Metric({
+            namespace: "CWAgent",
+            metricName: "disk_used_percent",
+            dimensionsMap: { AutoScalingGroupName: asgName },
+            period: Duration.minutes(5),
+            statistic: "Average"
+        }),
+        threshold: config.diskCriticalThreshold ?? 85,
+        evaluationPeriods: 2,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(diskCriticalAlarm, snsAction, alarms);
+    const stuckMergeMetricName = "ClickHouseStuckMergeCount";
+    new MetricFilter(scope, "ClickHouseStuckMergeMetricFilter", {
+        logGroup: webappLogGroup,
+        metricNamespace: CLICKHOUSE_METRIC_NAMESPACE,
+        metricName: stuckMergeMetricName,
+        filterPattern: FilterPattern.literal('"Stuck merge detected"'),
+        metricValue: "1",
+        defaultValue: 0
+    });
+    const stuckMergeAlarm = new Alarm(scope, "ClickHouseStuckMergeAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse merge stuck > 30 min — investigate parts pressure or replica health", undefined),
+        metric: new Metric({
+            namespace: CLICKHOUSE_METRIC_NAMESPACE,
+            metricName: stuckMergeMetricName,
+            period: Duration.minutes(5),
+            statistic: "Sum"
+        }),
+        threshold: 1,
+        evaluationPeriods: 2,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(stuckMergeAlarm, snsAction, alarms);
+    const backupFailureMetricName = "ClickHouseBackupFailureCount";
+    new MetricFilter(scope, "ClickHouseBackupFailureMetricFilter", {
+        logGroup: backupTaskLogGroup,
+        metricNamespace: CLICKHOUSE_METRIC_NAMESPACE,
+        metricName: backupFailureMetricName,
+        filterPattern: FilterPattern.anyTerm("AccessDenied", "S3Exception"),
+        metricValue: "1",
+        defaultValue: 0
+    });
+    const backupFailureAlarm = new Alarm(scope, "ClickHouseBackupFailureAlarm", {
+        alarmDescription: buildAlarmDescription(`ClickHouse BACKUP TO S3 emitted AccessDenied/S3Exception — verify instance role '${instanceRole.roleName}' grant on backup bucket`, undefined),
+        metric: new Metric({
+            namespace: CLICKHOUSE_METRIC_NAMESPACE,
+            metricName: backupFailureMetricName,
+            period: Duration.hours(1),
+            statistic: "Sum"
+        }),
+        threshold: 1,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(backupFailureAlarm, snsAction, alarms);
+    return alarms;
+}

package/dist/lib/resources/aws/monitoring/index.d.ts

@@ -2,3 +2,5 @@ export { ALARM_DEFAULTS, APPLICATION_ID_TAG_KEY, registerAlarm, tagAlarmsWithApp
 export { createEcsServiceAlarms, type EcsServiceAlarmThresholds, type EcsServiceAlarmsProps } from "./ecsAlarms.js";
 export { createRdsAlarms, type RdsAlarmThresholds, type RdsAlarmsProps } from "./rdsAlarms.js";
 export { createLambdaAlarms, type LambdaAlarmThresholds, type LambdaAlarmsProps } from "./lambdaAlarms.js";
+export { createScheduleAlarms, type ScheduleAlarmThresholds, type CreateScheduleAlarmsProps } from "./scheduleAlarms.js";
+export { createClickHouseAlarms, type ClickHouseAlarmThresholds, type ClickHouseAlarmsProps } from "./clickhouseAlarms.js";

package/dist/lib/resources/aws/monitoring/index.js

@@ -2,3 +2,5 @@ export { ALARM_DEFAULTS, APPLICATION_ID_TAG_KEY, registerAlarm, tagAlarmsWithApp
 export { createEcsServiceAlarms } from "./ecsAlarms.js";
 export { createRdsAlarms } from "./rdsAlarms.js";
 export { createLambdaAlarms } from "./lambdaAlarms.js";
+export { createScheduleAlarms } from "./scheduleAlarms.js";
+export { createClickHouseAlarms } from "./clickhouseAlarms.js";

package/dist/lib/resources/aws/monitoring/scheduleAlarms.d.ts

@@ -0,0 +1,47 @@
+import { Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { IRule } from "aws-cdk-lib/aws-events";
+import type { ITopic } from "aws-cdk-lib/aws-sns";
+import type { Construct } from "constructs";
+/**
+ * Tunable thresholds for the EventBridge schedule alarms. Lives here (NOT in
+ * `messaging/schedule.ts`) so the consumer module — `eventBridgeRule.ts` /
+ * `Schedule` — can re-export it without forming a circular import.
+ */
+export interface ScheduleAlarmThresholds {
+    failedInvocationsThreshold?: number;
+    throttledRulesThreshold?: number;
+    dlqFailureThreshold?: number;
+    /**
+     * Multiplier applied to `expectedTicksPerHour` to derive the missed-tick
+     * floor. Default 0.8 — fires when observed matches drop below 80% of the
+     * expected cadence (silent disablement detector).
+     */
+    matchedEventsLowFloorRatio?: number;
+}
+export interface CreateScheduleAlarmsProps {
+    scope: Construct;
+    ruleName: string;
+    rule: IRule;
+    kind: "schedule" | "subscription";
+    /** Populated by `parseRateExpression(...)` — undefined for cron schedules and subscriptions. */
+    expectedTicksPerHour?: number;
+    config?: ScheduleAlarmThresholds;
+    alarmTopic: ITopic;
+    applicationId?: string;
+    dlqEnabled: boolean;
+}
+/**
+ * Provisions D13 alarms for an EventBridge rule. Returns the created alarms
+ * (each wired to the SNS topic for both ALARM and OK transitions and tagged
+ * with the application id for webhook routing).
+ *
+ * Alarm coverage:
+ *   - `FailedInvocations` / `ThrottledRules` always fire.
+ *   - `InvocationsFailedToBeSentToDlq` fires only when `dlqEnabled === true`.
+ *   - `MatchedEvents` (missed-tick detector) fires only when
+ *     `kind === "schedule"` AND `expectedTicksPerHour !== undefined` —
+ *     i.e. rate expressions, not cron, not subscriptions. Uses
+ *     `LessThanThreshold` + `treatMissingData: BREACHING` so a fully silent
+ *     rule trips the alarm.
+ */
+export declare function createScheduleAlarms(props: CreateScheduleAlarmsProps): Alarm[];

package/dist/lib/resources/aws/monitoring/scheduleAlarms.js

@@ -0,0 +1,106 @@
+import { Duration } from "aws-cdk-lib";
+import { Alarm, ComparisonOperator, TreatMissingData, Metric } from "aws-cdk-lib/aws-cloudwatch";
+import { SnsAction } from "aws-cdk-lib/aws-cloudwatch-actions";
+import { ALARM_DEFAULTS, registerAlarm, tagAlarmsWithApplicationId, buildAlarmDescription } from "./alarmDefaults.js";
+const DEFAULT_THRESHOLDS = {
+    FAILED_INVOCATIONS: 1,
+    THROTTLED_RULES: 1,
+    DLQ_FAILURE: 1,
+    MATCHED_EVENTS_LOW_FLOOR_RATIO: 0.8
+};
+/**
+ * Provisions D13 alarms for an EventBridge rule. Returns the created alarms
+ * (each wired to the SNS topic for both ALARM and OK transitions and tagged
+ * with the application id for webhook routing).
+ *
+ * Alarm coverage:
+ *   - `FailedInvocations` / `ThrottledRules` always fire.
+ *   - `InvocationsFailedToBeSentToDlq` fires only when `dlqEnabled === true`.
+ *   - `MatchedEvents` (missed-tick detector) fires only when
+ *     `kind === "schedule"` AND `expectedTicksPerHour !== undefined` —
+ *     i.e. rate expressions, not cron, not subscriptions. Uses
+ *     `LessThanThreshold` + `treatMissingData: BREACHING` so a fully silent
+ *     rule trips the alarm.
+ */
+export function createScheduleAlarms(props) {
+    const { scope, ruleName, rule, kind, expectedTicksPerHour, config = {}, alarmTopic, applicationId, dlqEnabled } = props;
+    const alarms = [];
+    const snsAction = new SnsAction(alarmTopic);
+    const failedInvocationsThreshold = config.failedInvocationsThreshold ?? DEFAULT_THRESHOLDS.FAILED_INVOCATIONS;
+    const throttledRulesThreshold = config.throttledRulesThreshold ?? DEFAULT_THRESHOLDS.THROTTLED_RULES;
+    const dlqFailureThreshold = config.dlqFailureThreshold ?? DEFAULT_THRESHOLDS.DLQ_FAILURE;
+    const matchedEventsLowFloorRatio = config.matchedEventsLowFloorRatio ??
+        DEFAULT_THRESHOLDS.MATCHED_EVENTS_LOW_FLOOR_RATIO;
+    const ruleDimensions = { RuleName: rule.ruleName };
+    const failedInvocationsAlarm = new Alarm(scope, `${ruleName}FailedInvocationsAlarm`, {
+        alarmDescription: buildAlarmDescription(`EventBridge rule ${ruleName} FailedInvocations exceeds ${failedInvocationsThreshold}`, applicationId),
+        metric: new Metric({
+            namespace: "AWS/Events",
+            metricName: "FailedInvocations",
+            dimensionsMap: ruleDimensions,
+            period: ALARM_DEFAULTS.EVALUATION_PERIOD,
+            statistic: "Sum"
+        }),
+        threshold: failedInvocationsThreshold,
+        evaluationPeriods: 2,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(failedInvocationsAlarm, snsAction, alarms);
+    const throttledRulesAlarm = new Alarm(scope, `${ruleName}ThrottledRulesAlarm`, {
+        alarmDescription: buildAlarmDescription(`EventBridge rule ${ruleName} ThrottledRules exceeds ${throttledRulesThreshold}`, applicationId),
+        metric: new Metric({
+            namespace: "AWS/Events",
+            metricName: "ThrottledRules",
+            dimensionsMap: ruleDimensions,
+            period: ALARM_DEFAULTS.EVALUATION_PERIOD,
+            statistic: "Sum"
+        }),
+        threshold: throttledRulesThreshold,
+        evaluationPeriods: 2,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(throttledRulesAlarm, snsAction, alarms);
+    if (dlqEnabled) {
+        const dlqFailureAlarm = new Alarm(scope, `${ruleName}DlqFailureAlarm`, {
+            alarmDescription: buildAlarmDescription(`EventBridge rule ${ruleName} InvocationsFailedToBeSentToDlq exceeds ${dlqFailureThreshold}`, applicationId),
+            metric: new Metric({
+                namespace: "AWS/Events",
+                metricName: "InvocationsFailedToBeSentToDlq",
+                dimensionsMap: ruleDimensions,
+                period: Duration.minutes(5),
+                statistic: "Sum"
+            }),
+            threshold: dlqFailureThreshold,
+            evaluationPeriods: 1,
+            datapointsToAlarm: 1,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            treatMissingData: TreatMissingData.NOT_BREACHING
+        });
+        registerAlarm(dlqFailureAlarm, snsAction, alarms);
+    }
+    if (kind === "schedule" && expectedTicksPerHour !== undefined) {
+        const floor = Math.max(1, Math.floor(expectedTicksPerHour * matchedEventsLowFloorRatio));
+        const matchedEventsAlarm = new Alarm(scope, `${ruleName}MatchedEventsAlarm`, {
+            alarmDescription: buildAlarmDescription(`EventBridge rule ${ruleName} expected >=${floor} ticks/hour, observed <=${Math.round(matchedEventsLowFloorRatio * 100)}% threshold = silent disablement detector`, applicationId),
+            metric: new Metric({
+                namespace: "AWS/Events",
+                metricName: "MatchedEvents",
+                dimensionsMap: ruleDimensions,
+                period: Duration.hours(1),
+                statistic: "Sum"
+            }),
+            threshold: floor,
+            evaluationPeriods: 1,
+            datapointsToAlarm: 1,
+            comparisonOperator: ComparisonOperator.LESS_THAN_THRESHOLD,
+            treatMissingData: TreatMissingData.BREACHING
+        });
+        registerAlarm(matchedEventsAlarm, snsAction, alarms);
+    }
+    tagAlarmsWithApplicationId(alarms, applicationId);
+    return alarms;
+}

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

@@ -1,7 +1,7 @@
 import { Construct } from "constructs";
 import { Tags } from "aws-cdk-lib";
 import { CrossAccountZoneDelegationRecord as CdkCrossAccountZoneDelegationRecord } from "aws-cdk-lib/aws-route53";
-import { DEFAULT_COST_ALLOCATION_ENVIRONMENT } from "../../../utils/costAllocationTags.js";
+import { applyCostAllocationTags } from "../../../utils/costAllocationTags.js";
 // CDK's CrossAccountZoneDelegationRecord is a custom-resource Lambda: user-level tags
 // on the record itself may not reach AWS. We tag the wrapping Fjall Construct for
 // assertion purposes; create-path tags still propagate to child resources (Lambda,
@@ -20,8 +20,10 @@ export class CrossAccountDelegationRecord extends Construct {
             parentHostedZoneName: props.parentHostedZoneName
         });
         Tags.of(this).add("fjall:description", this.description);
-        Tags.of(this).add("fjall:costAllocation:environment", props.costAllocationEnvironment ?? DEFAULT_COST_ALLOCATION_ENVIRONMENT);
-        Tags.of(this).add("fjall:costAllocation:service", "crossAccountDelegation");
-        Tags.of(this).add("fjall:costAllocation:domain", props.costAllocationDomain ?? props.delegatedZoneName);
+        applyCostAllocationTags(this, {
+            service: "crossAccountDelegation",
+            domain: props.costAllocationDomain ?? props.delegatedZoneName,
+            environment: props.costAllocationEnvironment
+        });
     }
 }

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

@@ -1,5 +1,5 @@
 import { Construct } from "constructs";
-import { Duration } from "aws-cdk-lib";
+import { Duration, Fn } from "aws-cdk-lib";
 import { Runtime } from "aws-cdk-lib/aws-lambda";
 import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
 import { CustomResource } from "../utilities/customResource.js";
@@ -35,7 +35,7 @@ export class CrossAccountReturnRoutes extends Construct {
             properties: {
                 PeerRoleArn: props.peerRoleArn,
                 PeerRegion: props.peerRegion,
-                RouteTableIds: props.routeTableIds.join(","),
+                RouteTableIds: Fn.join(",", props.routeTableIds),
                 LocalVpcCidr: props.localVpcCidr,
                 PeeringConnectionId: props.peeringConnectionId,
                 EnableDns: props.enableDns === false ? "false" : "true"
@@ -107,13 +107,18 @@ exports.handler = async (event) => {
   if (event.RequestType === "Update") {
     const oldProps = event.OldResourceProperties || {};
     const oldRouteTableIds = parseRouteTableIds(oldProps.RouteTableIds);
+    const oldCidr = oldProps.LocalVpcCidr || props.LocalVpcCidr;
+    const cidrChanged = oldCidr !== props.LocalVpcCidr;
     const currentSet = new Set(routeTableIds);
-    const removedIds = oldRouteTableIds.filter((id) => !currentSet.has(id));
-    for (const routeTableId of removedIds) {
+    // CIDR change: stale routes persist on every kept table unless deleted by old CIDR first.
+    const idsToDeleteOldCidr = cidrChanged
+      ? oldRouteTableIds
+      : oldRouteTableIds.filter((id) => !currentSet.has(id));
+    for (const routeTableId of idsToDeleteOldCidr) {
       try {
         await ec2.send(new DeleteRouteCommand({
           RouteTableId: routeTableId,
-          DestinationCidrBlock: oldProps.LocalVpcCidr || props.LocalVpcCidr
+          DestinationCidrBlock: oldCidr
         }));
       } catch (err) {
         const name = err && err.name;
@@ -140,14 +145,13 @@ exports.handler = async (event) => {
     }
   }
 
-  if (props.EnableDns === "true") {
-    await ec2.send(new ModifyVpcPeeringConnectionOptionsCommand({
-      VpcPeeringConnectionId: props.PeeringConnectionId,
-      AccepterPeeringConnectionOptions: {
-        AllowDnsResolutionFromRemoteVpc: true
-      }
-    }));
-  }
+  // Always sent so a flip from true to false actually disables DNS — guarding on === "true" leaves it enabled forever.
+  await ec2.send(new ModifyVpcPeeringConnectionOptionsCommand({
+    VpcPeeringConnectionId: props.PeeringConnectionId,
+    AccepterPeeringConnectionOptions: {
+      AllowDnsResolutionFromRemoteVpc: props.EnableDns === "true"
+    }
+  }));
 
   return { PhysicalResourceId: physicalResourceId };
 };

package/dist/lib/resources/aws/networking/dnsRecord/dnsRecordBase.js

@@ -1,6 +1,6 @@
-import { Duration, Tags } from "aws-cdk-lib";
+import { Duration } from "aws-cdk-lib";
 import { DNS_APEX } from "@fjall/util";
-import { DEFAULT_COST_ALLOCATION_ENVIRONMENT } from "../../../../utils/costAllocationTags.js";
+import { applyCostAllocationTags } from "../../../../utils/costAllocationTags.js";
 export const DEFAULT_DNS_TTL_SECONDS = 300;
 export function resolveFqdn(zoneName, recordName) {
     return recordName === DNS_APEX ? zoneName : `${recordName}.${zoneName}`;
@@ -12,7 +12,9 @@ export function defaultDnsComment(recordType, fqdn) {
     return `Fjall-managed ${recordType} record for ${fqdn}`;
 }
 export function applyDnsRecordTags(construct, props) {
-    Tags.of(construct).add("fjall:costAllocation:environment", props.costAllocationEnvironment ?? DEFAULT_COST_ALLOCATION_ENVIRONMENT);
-    Tags.of(construct).add("fjall:costAllocation:service", "dnsRecord");
-    Tags.of(construct).add("fjall:costAllocation:domain", props.costAllocationDomain ?? props.zoneName);
+    applyCostAllocationTags(construct, {
+        service: "dnsRecord",
+        domain: props.costAllocationDomain ?? props.zoneName,
+        environment: props.costAllocationEnvironment
+    });
 }

package/dist/lib/resources/aws/networking/domainCertificate.d.ts

@@ -1,5 +1,5 @@
 import { Construct } from "constructs";
-import { Certificate } from "aws-cdk-lib/aws-certificatemanager";
+import { type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
 import { type IHostedZone } from "aws-cdk-lib/aws-route53";
 export interface DomainCertificateProps {
     readonly domainName: string;
@@ -11,7 +11,7 @@ export interface DomainCertificateProps {
     readonly costAllocationDomain?: string;
 }
 export declare class DomainCertificate extends Construct {
-    readonly certificate: Certificate;
+    readonly certificate: ICertificate;
     readonly certificateArn: string;
     readonly description: string;
     constructor(scope: Construct, id: string, props: DomainCertificateProps);

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

@@ -3,7 +3,7 @@ import { CfnOutput, Tags } from "aws-cdk-lib";
 import { Certificate, CertificateValidation } from "aws-cdk-lib/aws-certificatemanager";
 import { getDomainExportNames } from "@fjall/util";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
-import { DEFAULT_COST_ALLOCATION_ENVIRONMENT } from "../../../utils/costAllocationTags.js";
+import { applyCostAllocationTags } from "../../../utils/costAllocationTags.js";
 export class DomainCertificate extends Construct {
     certificate;
     certificateArn;
@@ -21,9 +21,11 @@ export class DomainCertificate extends Construct {
         });
         this.certificateArn = this.certificate.certificateArn;
         Tags.of(this).add("fjall:description", this.description);
-        Tags.of(this).add("fjall:costAllocation:environment", props.costAllocationEnvironment ?? DEFAULT_COST_ALLOCATION_ENVIRONMENT);
-        Tags.of(this).add("fjall:costAllocation:service", "certificate");
-        Tags.of(this).add("fjall:costAllocation:domain", props.costAllocationDomain ?? props.domainName);
+        applyCostAllocationTags(this, {
+            service: "certificate",
+            domain: props.costAllocationDomain ?? props.domainName,
+            environment: props.costAllocationEnvironment
+        });
         const safeKey = toPascalCase(props.domainName.split(".").join(""));
         const exports = getDomainExportNames(props.domainName);
         new CfnOutput(this, `${safeKey}CertificateArn`, {

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

@@ -4,7 +4,7 @@ import { HostedZone as AWSHostedZone } from "aws-cdk-lib/aws-route53";
 import { getDomainExportNames } from "@fjall/util";
 import { toPascalCase, getSafeZoneName } from "../../../utils/capitaliseString.js";
 import { DelegationRole } from "../iam/delegationRole.js";
-import { DEFAULT_COST_ALLOCATION_ENVIRONMENT } from "../../../utils/costAllocationTags.js";
+import { applyCostAllocationTags } from "../../../utils/costAllocationTags.js";
 export class HostedZoneFactory {
     static import(stack, hostedZoneId, zoneName, opts) {
         const safeZone = toPascalCase(getSafeZoneName(zoneName));
@@ -71,10 +71,11 @@ export class HostedZone extends Construct {
             this.isImported = true;
             Tags.of(this).add("fjall:description", this.description);
         }
-        // Cost allocation tags applied uniformly on both create and import paths.
-        Tags.of(this).add("fjall:costAllocation:environment", props.costAllocationEnvironment ?? DEFAULT_COST_ALLOCATION_ENVIRONMENT);
-        Tags.of(this).add("fjall:costAllocation:service", "hostedZone");
-        Tags.of(this).add("fjall:costAllocation:domain", props.costAllocationDomain ?? props.zoneName);
+        applyCostAllocationTags(this, {
+            service: "hostedZone",
+            domain: props.costAllocationDomain ?? props.zoneName,
+            environment: props.costAllocationEnvironment
+        });
         new CfnOutput(this, `${safeZone}HostedZoneId`, {
             key: `${safeZone}HostedZoneId`,
             value: this.hostedZoneId,

package/dist/lib/resources/aws/networking/serviceDiscovery.d.ts

@@ -0,0 +1,96 @@
+import { Construct } from "constructs";
+import { Duration } from "aws-cdk-lib";
+import { type IVpc } from "aws-cdk-lib/aws-ec2";
+import { type IPrivateDnsNamespace, type IService } from "aws-cdk-lib/aws-servicediscovery";
+/**
+ * Plumbing-only base resource wrapping `aws-cdk-lib/aws-servicediscovery`'s
+ * `PrivateDnsNamespace`. Per D7 + D29 of the ClickHouse Database Factory
+ * promotion design, the only consumer entry point is `App.getNamespace()` —
+ * this class is NOT re-exported from `lib/index.ts`.
+ *
+ * No `static fromXxx(...)` factory is exposed: cross-stack consumption is
+ * single-stack-only for v1 per D29. If/when cross-stack arises, a `fromXxx`
+ * factory lands then, not now.
+ */
+export interface ServiceDiscoveryNamespaceProps {
+    vpc: IVpc;
+    name: string;
+    /** Override the default description (`"ServiceDiscovery <name> — Fjall private DNS namespace"`). */
+    description?: string;
+    /**
+     * Removal policy. Default resolves via the `env()` helper (production →
+     * RETAIN; non-prod → DESTROY) — matches the convention codified in D17 of
+     * the EventBridge promotion design. NODE_ENV is intentionally NOT consulted
+     * because it is unset during CDK synth in Fjall's deployment paths.
+     */
+    removalPolicy?: "DESTROY" | "RETAIN";
+}
+/**
+ * Properties for registering a Cloud Map service inside the namespace via
+ * `registerService(...)`. Single source of truth for the second-tier wrapper
+ * around `AWS::ServiceDiscovery::Service`. Per D7(d), this method is
+ * internal-only — never consumed directly from user infrastructure code.
+ */
+export interface ServiceRegistrationProps {
+    /** Service name within the namespace (forms the leftmost label of the FQDN). */
+    name: string;
+    /**
+     * Description override. Default: `"Fjall internal service: <name>"`.
+     * Operators see this in the Cloud Map console; explicit overrides are
+     * preferred when the service name alone is ambiguous (e.g. `"clickhouse"`
+     * is fine; `"web"` benefits from a description naming the role).
+     */
+    description?: string;
+    /**
+     * DNS TTL applied to the A records returned for this service. Default:
+     * 60 seconds — matches CDK's implicit ECS default. Raise for stable
+     * services (cuts query volume); lower for rapidly-changing instance sets.
+     */
+    dnsTtl?: Duration;
+    /**
+     * DNS record type. Default `"A"` — appropriate for `awsvpc` ECS services
+     * where each task has its own ENI IP. Set to `"SRV"` when the consumer is
+     * an ECS service running under `host` or `bridge` network mode: SRV records
+     * carry both the host IP and the published port, which `A` records cannot.
+     * CDK's `Ec2Service.associateCloudMapService(...)` requires SRV (and a
+     * `containerName` + `containerPort`) under those modes.
+     */
+    dnsRecordType?: "A" | "SRV";
+}
+export declare class ServiceDiscoveryNamespace extends Construct {
+    #private;
+    readonly id: string;
+    constructor(scope: Construct, id: string, props: ServiceDiscoveryNamespaceProps);
+    /**
+     * Get the underlying CDK private DNS namespace as the `IPrivateDnsNamespace`
+     * interface. Per D18(a), the public surface is the interface, never the
+     * concrete `PrivateDnsNamespace` class.
+     */
+    getNamespace(): IPrivateDnsNamespace;
+    getNamespaceArn(): string;
+    getNamespaceName(): string;
+    /**
+     * Register a Cloud Map service inside this namespace. Creates an
+     * `AWS::ServiceDiscovery::Service` resource via the underlying CDK
+     * `PrivateDnsNamespace.createService(...)` with Fjall description discipline
+     * applied. Internal-only per D7(d) — Fjall resources call this from inside
+     * their construct bodies; user code never invokes it directly.
+     *
+     * Throws on duplicate registration: a single namespace cannot host two
+     * services with the same DNS name. Caught at synth time, not deploy time.
+     */
+    registerService(props: ServiceRegistrationProps): IService;
+    /**
+     * True if a service with this name has been registered in the namespace.
+     * Cheap registry lookup; does NOT consult AWS — only counts services
+     * registered via `registerService(...)` on this construct.
+     */
+    hasService(name: string): boolean;
+    /**
+     * Build the FQDN for a previously-registered service:
+     * `<serviceName>.<namespaceName>` (e.g. `clickhouse.acme.local`). Throws if
+     * the service has not been registered — prevents typos that would silently
+     * resolve to NXDOMAIN at runtime.
+     */
+    getEndpoint(serviceName: string): string;
+}