@fjall/components-infrastructure 16.0.1 → 18.0.0

package/dist/lib/resources/aws/database/clickhouseSchemas.d.ts

@@ -23,6 +23,19 @@ export type ClickHouseSchemaAdmin = z.infer<typeof ClickHouseSchemaAdminSchema>;
  */
 export declare const ManagedPasswordNameSchema: z.ZodString;
 export type ManagedPasswordName = z.infer<typeof ManagedPasswordNameSchema>;
+/**
+ * One setting's constraint inside a profile's `<constraints>` block.
+ * `max`/`min` bound what a statement-level `SETTINGS` clause may set the
+ * value to; `readonly` forbids changing it at all. A statement that tries
+ * to exceed a bound fails with 452 SETTING_CONSTRAINT_VIOLATION instead of
+ * silently widening its own budget.
+ */
+export declare const SettingConstraintSchema: z.ZodObject<{
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    readonly: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+export type SettingConstraint = z.infer<typeof SettingConstraintSchema>;
 /**
  * Per-profile resource-cap shape. Field names mirror the ClickHouse XML
  * element names (snake_case at the wire; camelCase here for TS ergonomics).
@@ -31,8 +44,18 @@ export type ManagedPasswordName = z.infer<typeof ManagedPasswordNameSchema>;
  * `renderUsersXml` maps each present field to the snake_case XML element
  * via `camelToSnakeCase`. Unknown fields are rejected by `.strict()` so a
  * typo at the consumer doesn't silently ship a no-op profile.
+ *
+ * `constraints` is the one non-scalar member: it renders as the profile's
+ * `<constraints>` block (keys camelCase here, snake_case at the wire, same
+ * as the scalar settings), making the named ceilings unraisable from a
+ * statement-level `SETTINGS` clause.
  */
 export declare const ProfileSpecSchema: z.ZodObject<{
+    constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        readonly: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strict>>>;
     maxThreads: z.ZodOptional<z.ZodNumber>;
     maxInsertThreads: z.ZodOptional<z.ZodNumber>;
     maxConcurrentQueriesForUser: z.ZodOptional<z.ZodNumber>;
@@ -62,6 +85,15 @@ export declare const ProfileSpecSchema: z.ZodObject<{
     materializeTtlAfterModify: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type ProfileSpec = z.infer<typeof ProfileSpecSchema>;
+/**
+ * Deep-frozen `ProfileSpec` — matches the `Object.freeze` depth of the
+ * derived defaults so the type system forbids what the runtime freeze
+ * throws on. `Readonly<ProfileSpec>` alone is shallow: it left the nested
+ * constraint objects typed mutable while frozen at runtime.
+ */
+export type FrozenProfileSpec = Readonly<Omit<ProfileSpec, "constraints">> & {
+    readonly constraints?: Readonly<Record<string, Readonly<SettingConstraint>>>;
+};
 /**
  * Re-exported for the construct's Stage 1 validation. Profile keys MUST
  * match the same lowercase snake_case shape as user names — they emit as
@@ -88,4 +120,4 @@ export declare const PROFILE_NAME_PATTERN: RegExp;
  * consumer cannot mutate the defaults in place. Pass your own `profiles:`
  * map to the construct to extend / override; never mutate this constant.
  */
-export declare const ClickHouseDefaultProfiles: Readonly<Record<string, Readonly<ProfileSpec>>>;
+export declare const ClickHouseDefaultProfiles: Readonly<Record<string, FrozenProfileSpec>>;

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

@@ -9,6 +9,12 @@ import { deriveClickHouseDefaultProfiles } from "./clickhouseTuning.js";
  *  surfaces as a parse failure in the runner). Keeps the XML element names
  *  emit-safe (no escaping needed). */
 const NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+/** Constraint-record keys — camelCase (or snake_case) setting names with a
+ *  leading lowercase letter. Record keys are the one profile surface
+ *  `.strict()` cannot police, and they emit as XML element names via
+ *  `camelToSnakeCase`, so the emit-safety NAME_PATTERN guarantees for
+ *  user/profile names must come from the key schema itself here. */
+const CONSTRAINT_KEY_PATTERN = /^[a-z][a-zA-Z0-9_]*$/;
 /**
  * Schema-admin user — the framework's bootstrap-privileged identity that
  * customer SQL runs as. Owns DDL, schema migrations, GRANTs. Rendered into
@@ -41,6 +47,21 @@ export const ManagedPasswordNameSchema = z
     .min(1)
     .max(63)
     .regex(NAME_PATTERN, "Must be lowercase snake_case");
+/**
+ * One setting's constraint inside a profile's `<constraints>` block.
+ * `max`/`min` bound what a statement-level `SETTINGS` clause may set the
+ * value to; `readonly` forbids changing it at all. A statement that tries
+ * to exceed a bound fails with 452 SETTING_CONSTRAINT_VIOLATION instead of
+ * silently widening its own budget.
+ */
+export const SettingConstraintSchema = z
+    .object({
+    min: z.number().int().nonnegative().optional(),
+    max: z.number().int().nonnegative().optional(),
+    readonly: z.literal(true).optional()
+})
+    .strict()
+    .refine((c) => c.min !== undefined || c.max !== undefined || c.readonly === true, "A setting constraint must declare min, max or readonly");
 /**
  * Per-profile resource-cap shape. Field names mirror the ClickHouse XML
  * element names (snake_case at the wire; camelCase here for TS ergonomics).
@@ -49,9 +70,19 @@ export const ManagedPasswordNameSchema = z
  * `renderUsersXml` maps each present field to the snake_case XML element
  * via `camelToSnakeCase`. Unknown fields are rejected by `.strict()` so a
  * typo at the consumer doesn't silently ship a no-op profile.
+ *
+ * `constraints` is the one non-scalar member: it renders as the profile's
+ * `<constraints>` block (keys camelCase here, snake_case at the wire, same
+ * as the scalar settings), making the named ceilings unraisable from a
+ * statement-level `SETTINGS` clause.
  */
 export const ProfileSpecSchema = z
     .object({
+    constraints: z
+        .record(z
+        .string()
+        .regex(CONSTRAINT_KEY_PATTERN, "Constraint keys must be camelCase (or snake_case) setting names"), SettingConstraintSchema)
+        .optional(),
     maxThreads: z.number().int().positive().optional(),
     maxInsertThreads: z.number().int().positive().optional(),
     maxConcurrentQueriesForUser: z.number().int().positive().optional(),

package/dist/lib/resources/aws/database/clickhouseStorage.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Default critical free-space floor for a volume of `storageGb`.
+ *
+ * The larger of the absolute floor and a share of the volume — neither alone
+ * is right at both ends of the size range. See
+ * `CLICKHOUSE_DISK_FREE_CRITICAL_GIB` for the reasoning; rounded to whole GiB
+ * so the alarm description reads as a number an operator would say out loud.
+ */
+export declare function defaultDiskFreeCriticalGib(storageGb: number): number;
+export interface ClickHouseStorageResolution {
+    /** EBS volume size in GiB, defaulted and validated. */
+    storageGb: number;
+    /** Critical free-space floor in GiB, defaulted and validated. */
+    diskFreeCriticalGib: number;
+}
+/**
+ * Resolve and validate the two values that together decide when a ClickHouse
+ * volume is considered nearly full.
+ *
+ * They are validated as a PAIR because neither is checkable alone: a 100 GiB
+ * volume is fine until someone sets a 60 GiB free-space floor, and a 60 GiB
+ * floor is fine until someone shrinks the volume under it. Split across two
+ * validators, each would pass on its own and the deployed stack would carry a
+ * critical alarm that can never leave ALARM.
+ *
+ * Throws rather than annotating: both are numbers the caller typed, and a
+ * warning on a synth that still emits a permanently-breaching pager is worse
+ * than a failed synth with the arithmetic in the message.
+ */
+export declare function resolveClickHouseStorage(storageGb: number | undefined, diskFreeCriticalGib: number | undefined): ClickHouseStorageResolution;
+export interface ClickHouseVolumePerformanceInput {
+    /** Validated volume size from `resolveClickHouseStorage` — the IOPS ceiling
+     *  is a function of it. */
+    storageGb: number;
+    iops: number | undefined;
+    throughputMbps: number | undefined;
+}
+export interface ClickHouseVolumePerformanceResolution {
+    /** Provisioned IOPS, defaulted and validated. */
+    iops: number;
+    /** Provisioned throughput in MiB/s, defaulted and validated. */
+    throughputMbps: number;
+}
+/**
+ * Resolve and validate the gp3 performance pair for the data volume.
+ *
+ * Same shape as `resolveClickHouseStorage`: each value has a band of its own,
+ * but EBS also constrains them against each other and against the size —
+ * throughput needs four IOPS per MiB/s, and IOPS needs a GiB per 500 — so a
+ * value legal on its own is rejected by CreateVolume mid-deploy once its
+ * partner is in view. Checking the pair at synth turns that rollback into a
+ * message that names the figure the other half needs.
+ *
+ * Both checks are the ones aws-cdk-lib's `Volume` applies too; this resolver
+ * exists so the failure names `ClickHouseDatabase` props and their cure
+ * rather than a CDK-internal field.
+ */
+export declare function resolveClickHouseVolumePerformance(input: ClickHouseVolumePerformanceInput): ClickHouseVolumePerformanceResolution;

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

@@ -0,0 +1,87 @@
+import { CLICKHOUSE_DISK_FREE_CRITICAL_GIB, CLICKHOUSE_DISK_FREE_CRITICAL_SHARE, CLICKHOUSE_EBS_IOPS, CLICKHOUSE_EBS_THROUGHPUT_MBPS, CLICKHOUSE_EBS_VOLUME_SIZE_GB, CLICKHOUSE_IOPS_PER_THROUGHPUT_MBPS, CLICKHOUSE_MAX_IOPS, CLICKHOUSE_MAX_IOPS_PER_GB, CLICKHOUSE_MAX_STORAGE_GB, CLICKHOUSE_MAX_THROUGHPUT_MBPS, CLICKHOUSE_MIN_IOPS, CLICKHOUSE_MIN_STORAGE_GB, CLICKHOUSE_MIN_THROUGHPUT_MBPS } from "./clickhouseConstants.js";
+/**
+ * Largest share of the volume the critical free-space floor may claim. A
+ * floor at half the disk would page from the day the cluster passed 50 %
+ * used, which is a capacity-planning fact, not an incident; at a fifth, the
+ * alarm means what its description says — the disk is nearly gone.
+ */
+const MAX_FLOOR_SHARE_OF_VOLUME = 0.2;
+/**
+ * Default critical free-space floor for a volume of `storageGb`.
+ *
+ * The larger of the absolute floor and a share of the volume — neither alone
+ * is right at both ends of the size range. See
+ * `CLICKHOUSE_DISK_FREE_CRITICAL_GIB` for the reasoning; rounded to whole GiB
+ * so the alarm description reads as a number an operator would say out loud.
+ */
+export function defaultDiskFreeCriticalGib(storageGb) {
+    return Math.max(CLICKHOUSE_DISK_FREE_CRITICAL_GIB, Math.round(storageGb * CLICKHOUSE_DISK_FREE_CRITICAL_SHARE));
+}
+/**
+ * Resolve and validate the two values that together decide when a ClickHouse
+ * volume is considered nearly full.
+ *
+ * They are validated as a PAIR because neither is checkable alone: a 100 GiB
+ * volume is fine until someone sets a 60 GiB free-space floor, and a 60 GiB
+ * floor is fine until someone shrinks the volume under it. Split across two
+ * validators, each would pass on its own and the deployed stack would carry a
+ * critical alarm that can never leave ALARM.
+ *
+ * Throws rather than annotating: both are numbers the caller typed, and a
+ * warning on a synth that still emits a permanently-breaching pager is worse
+ * than a failed synth with the arithmetic in the message.
+ */
+export function resolveClickHouseStorage(storageGb, diskFreeCriticalGib) {
+    const size = storageGb ?? CLICKHOUSE_EBS_VOLUME_SIZE_GB;
+    if (!Number.isInteger(size) ||
+        size < CLICKHOUSE_MIN_STORAGE_GB ||
+        size > CLICKHOUSE_MAX_STORAGE_GB) {
+        throw new Error(`ClickHouseDatabase: storageGb must be an integer between ${CLICKHOUSE_MIN_STORAGE_GB} and ${CLICKHOUSE_MAX_STORAGE_GB} GiB; got ${size}.`);
+    }
+    const floor = diskFreeCriticalGib ?? defaultDiskFreeCriticalGib(size);
+    if (!Number.isFinite(floor) || floor <= 0) {
+        throw new Error(`ClickHouseDatabase: alarms.diskFreeCriticalGib must be a positive number of GiB; got ${floor}.`);
+    }
+    const ceiling = size * MAX_FLOOR_SHARE_OF_VOLUME;
+    if (floor > ceiling) {
+        throw new Error(`ClickHouseDatabase: alarms.diskFreeCriticalGib (${floor} GiB) exceeds a fifth of storageGb (${size} GiB → ${ceiling} GiB). A floor that large keeps the disk-critical alarm in ALARM on a healthy cluster; raise storageGb or lower the floor.`);
+    }
+    return { storageGb: size, diskFreeCriticalGib: floor };
+}
+/**
+ * Resolve and validate the gp3 performance pair for the data volume.
+ *
+ * Same shape as `resolveClickHouseStorage`: each value has a band of its own,
+ * but EBS also constrains them against each other and against the size —
+ * throughput needs four IOPS per MiB/s, and IOPS needs a GiB per 500 — so a
+ * value legal on its own is rejected by CreateVolume mid-deploy once its
+ * partner is in view. Checking the pair at synth turns that rollback into a
+ * message that names the figure the other half needs.
+ *
+ * Both checks are the ones aws-cdk-lib's `Volume` applies too; this resolver
+ * exists so the failure names `ClickHouseDatabase` props and their cure
+ * rather than a CDK-internal field.
+ */
+export function resolveClickHouseVolumePerformance(input) {
+    const iops = input.iops ?? CLICKHOUSE_EBS_IOPS;
+    if (!Number.isInteger(iops) ||
+        iops < CLICKHOUSE_MIN_IOPS ||
+        iops > CLICKHOUSE_MAX_IOPS) {
+        throw new Error(`ClickHouseDatabase: iops must be an integer between ${CLICKHOUSE_MIN_IOPS} and ${CLICKHOUSE_MAX_IOPS}; got ${iops}.`);
+    }
+    const iopsCeilingForSize = input.storageGb * CLICKHOUSE_MAX_IOPS_PER_GB;
+    if (iops > iopsCeilingForSize) {
+        throw new Error(`ClickHouseDatabase: iops (${iops}) exceeds ${CLICKHOUSE_MAX_IOPS_PER_GB} per GiB of storageGb (${input.storageGb} GiB → ${iopsCeilingForSize}). EBS rejects the volume; raise storageGb to at least ${Math.ceil(iops / CLICKHOUSE_MAX_IOPS_PER_GB)} GiB or lower iops.`);
+    }
+    const throughputMbps = input.throughputMbps ?? CLICKHOUSE_EBS_THROUGHPUT_MBPS;
+    if (!Number.isInteger(throughputMbps) ||
+        throughputMbps < CLICKHOUSE_MIN_THROUGHPUT_MBPS ||
+        throughputMbps > CLICKHOUSE_MAX_THROUGHPUT_MBPS) {
+        throw new Error(`ClickHouseDatabase: throughputMbps must be an integer between ${CLICKHOUSE_MIN_THROUGHPUT_MBPS} and ${CLICKHOUSE_MAX_THROUGHPUT_MBPS} MiB/s; got ${throughputMbps}.`);
+    }
+    const iopsNeeded = throughputMbps * CLICKHOUSE_IOPS_PER_THROUGHPUT_MBPS;
+    if (iops < iopsNeeded) {
+        throw new Error(`ClickHouseDatabase: throughputMbps (${throughputMbps} MiB/s) needs ${CLICKHOUSE_IOPS_PER_THROUGHPUT_MBPS} IOPS per MiB/s, so at least ${iopsNeeded} iops; got ${iops}. EBS rejects the volume; raise iops to ${iopsNeeded} or lower throughputMbps to ${Math.floor(iops / CLICKHOUSE_IOPS_PER_THROUGHPUT_MBPS)}.`);
+    }
+    return { iops, throughputMbps };
+}

package/dist/lib/resources/aws/database/clickhouseTuning.d.ts

@@ -1,4 +1,4 @@
-import type { ProfileSpec } from "./clickhouseSchemas.js";
+import type { FrozenProfileSpec } from "./clickhouseSchemas.js";
 /**
  * Server-level tuning values derived from the instance type. Consumed by
  * `generateServerConfigXml` — every value here lands in the rendered
@@ -50,10 +50,9 @@ export declare const SYSTEM_LOG_TTL = "event_date + INTERVAL 14 DAY DELETE";
 export declare function deriveClickHouseServerTuning(instanceType: string): ClickHouseServerTuning;
 /**
  * Derive the four workload-class default profiles from the instance type.
- * Memory caps, external-spill thresholds and row-read ceilings scale with
- * instance memory; thread caps scale with vCPUs. At the default
- * m7g.medium this reproduces the historical hand-tuned values exactly
- * (pinned by clickhouseTuning.test.ts).
+ * Memory caps, external-spill thresholds and constraint ceilings scale with
+ * instance memory; thread caps scale with vCPUs. The full m7g.medium
+ * shape is pinned by clickhouseTuning.test.ts.
  *
  * `high_throughput_ingest.maxConcurrentQueriesForUser` deliberately does
  * NOT scale: it mirrors the webapp's client-side FIFO gate
@@ -61,4 +60,4 @@ export declare function deriveClickHouseServerTuning(instanceType: string): Clic
  * parity test on the webapp side enforces the pair, so the value is a
  * client contract, not an instance-capacity knob.
  */
-export declare function deriveClickHouseDefaultProfiles(instanceType: string): Readonly<Record<string, Readonly<ProfileSpec>>>;
+export declare function deriveClickHouseDefaultProfiles(instanceType: string): Readonly<Record<string, FrozenProfileSpec>>;

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

@@ -1,4 +1,4 @@
-import { CLICKHOUSE_INSTANCE_SPECS } from "./clickhouseConstants.js";
+import { clickHouseInstanceSpec, CLICKHOUSE_INSTANCE_SPECS } from "./clickhouseConstants.js";
 /** 4 GiB / 1 vCPU (m7g.medium) baseline the scaling formulas anchor to.
  *  These are the proven prod values the construct shipped hand-tuned before
  *  derivation existed — `deriveClickHouseServerTuning("m7g.medium")` must
@@ -47,7 +47,7 @@ export const MAX_SERVER_MEMORY_RAM_RATIO = 0.75;
  *  change is a single edit. */
 export const SYSTEM_LOG_TTL = "event_date + INTERVAL 14 DAY DELETE";
 function resolveSpec(instanceType) {
-    const spec = CLICKHOUSE_INSTANCE_SPECS[instanceType];
+    const spec = clickHouseInstanceSpec(instanceType);
     if (spec === undefined) {
         throw new Error(`ClickHouseDatabase: unknown instance type '${instanceType}' — cannot ` +
             "derive server tuning. Supported: " +
@@ -110,10 +110,9 @@ export function deriveClickHouseServerTuning(instanceType) {
 }
 /**
  * Derive the four workload-class default profiles from the instance type.
- * Memory caps, external-spill thresholds and row-read ceilings scale with
- * instance memory; thread caps scale with vCPUs. At the default
- * m7g.medium this reproduces the historical hand-tuned values exactly
- * (pinned by clickhouseTuning.test.ts).
+ * Memory caps, external-spill thresholds and constraint ceilings scale with
+ * instance memory; thread caps scale with vCPUs. The full m7g.medium
+ * shape is pinned by clickhouseTuning.test.ts.
  *
  * `high_throughput_ingest.maxConcurrentQueriesForUser` deliberately does
  * NOT scale: it mirrors the webapp's client-side FIFO gate
@@ -124,12 +123,27 @@ export function deriveClickHouseServerTuning(instanceType) {
 export function deriveClickHouseDefaultProfiles(instanceType) {
     const spec = resolveSpec(instanceType);
     const scale = memoryScale(spec);
+    // The four unraisable ceilings — one source for both the ingest profile's
+    // scalar defaults and its <constraints> block, so a retuned default can
+    // never drift from (or exceed) its own ceiling.
+    const ingestCeilings = Object.freeze({
+        maxThreads: spec.vcpus,
+        maxMemoryUsage: 1610612736 * scale, // 1.5 GiB baseline
+        maxMemoryUsageForUser: 2147483648 * scale, // 2 GiB baseline
+        maxExecutionTime: 30
+    });
     return Object.freeze({
         high_throughput_ingest: Object.freeze({
-            maxThreads: spec.vcpus,
+            maxThreads: ingestCeilings.maxThreads,
             maxInsertThreads: spec.vcpus,
             maxConcurrentQueriesForUser: 6,
-            logQueriesMinQueryDurationMs: 100,
+            // MUST stay 0: any non-zero value drops ALL ExceptionBeforeStart rows
+            // (quota / concurrency / limit refusals) and every QueryStart row from
+            // system.query_log unconditionally (executeQuery.cpp gates on elapsed
+            // time, which refused queries never accrue) — failed product queries
+            // become invisible. If log volume ever needs a lever it is
+            // log_queries_min_type=QUERY_FINISH, never a duration floor.
+            logQueriesMinQueryDurationMs: 0,
             optimizeMoveToPrewhere: true,
             useQueryConditionCache: true,
             useSkipIndexesIfFinal: true,
@@ -146,16 +160,25 @@ export function deriveClickHouseDefaultProfiles(instanceType) {
             inputFormatParallelParsing: false,
             outputFormatParallelFormatting: false,
             queryPlanOptimizeLazyMaterialization: true,
-            maxMemoryUsage: 1610612736 * scale, // 1.5 GiB baseline
-            maxMemoryUsageForUser: 2147483648 * scale, // 2 GiB baseline
+            maxMemoryUsage: ingestCeilings.maxMemoryUsage,
+            maxMemoryUsageForUser: ingestCeilings.maxMemoryUsageForUser,
             maxBytesBeforeExternalSort: 536870912 * scale, // 512 MiB baseline
             maxBytesBeforeExternalGroupBy: 536870912 * scale,
-            maxExecutionTime: 30,
-            // The ceiling an unbounded consumer query dies against (TOO_MANY_ROWS).
-            // Scales with memory so a bigger node's tables get proportionate
-            // headroom — but consumers must still time-bound their scans; this is
-            // a guard rail, not a budget to grow into.
-            maxRowsToRead: 10000000 * scale
+            maxExecutionTime: ingestCeilings.maxExecutionTime,
+            // Deliberately no maxRowsToRead: the planning-time estimate refuses
+            // legitimate in-order LIMIT reads, and any statement can override it.
+            // Per-box protection is the unraisable ceilings below; per-tenant
+            // fairness is the org-keyed quota (webapp clickhouse-init/030).
+            constraints: Object.freeze({
+                maxExecutionTime: Object.freeze({
+                    max: ingestCeilings.maxExecutionTime
+                }),
+                maxMemoryUsage: Object.freeze({ max: ingestCeilings.maxMemoryUsage }),
+                maxMemoryUsageForUser: Object.freeze({
+                    max: ingestCeilings.maxMemoryUsageForUser
+                }),
+                maxThreads: Object.freeze({ max: ingestCeilings.maxThreads })
+            })
         }),
         audit_append: Object.freeze({
             maxThreads: 1,

package/dist/lib/resources/aws/database/clickhouseUserData.d.ts

@@ -18,6 +18,17 @@ export interface BuildClickHouseUserDataOptions {
      * as `clickHouseTaskMemoryMiB`).
      */
     instanceType: string;
+    /**
+     * Declared data-volume size in GiB, embedded into the emitted script as a
+     * comment line. Load-bearing, not documentation: user data is part of the
+     * launch template, so embedding the size means a `storageGb` change
+     * produces a new launch-template version — which is what triggers the ASG
+     * instance refresh whose boot runs the `resize2fs` below. Without it, a
+     * volume increase modifies the EBS device in place, nothing relaunches,
+     * and the grown capacity is inert until some unrelated deploy happens to
+     * replace the instance. Same apply mechanism `instanceType` rides.
+     */
+    dataVolumeSizeGb: number;
     /**
      * Optional S3 cold-tier configuration.
      * When omitted, single-tier hot storage on the EC2 EBS volume is used.
@@ -52,7 +63,16 @@ export interface BuildClickHouseUserDataOptions {
         serverSecretArn: string;
     };
 }
-export declare function generateServerConfigXml(options: BuildClickHouseUserDataOptions): string;
+/**
+ * The subset of the user-data options that config.xml generation actually
+ * reads. `dataVolumeSizeGb` is deliberately absent: it shapes the boot
+ * SCRIPT (the launch-template refresh trigger), not the rendered server
+ * config — demanding it here forced the XML parity tests to invent a value
+ * the render never consumes. `tls` is read for presence only (it toggles
+ * the secure-listener block); the ARNs inside it are boot-script concerns.
+ */
+export type ServerConfigXmlOptions = Pick<BuildClickHouseUserDataOptions, "backupBucketName" | "backupBucketRegion" | "instanceType" | "coldTier" | "tls">;
+export declare function generateServerConfigXml(options: ServerConfigXmlOptions): string;
 export interface GenerateUsersConfigXmlOptions {
     schemaAdmin: ClickHouseSchemaAdmin;
     profiles: Record<string, ProfileSpec>;

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

@@ -362,9 +362,14 @@ chmod 644 "$MOUNT_POINT/server-certs/client.xml"
 `
         : "";
     // The CWAgent-namespace metrics have no producer without this — no
-    // CloudWatch Agent is installed. disk_used_percent feeds the host disk
-    // alarms; mem_used_percent is dashboards-only (the CWAgent memory alarm is
-    // retired — memory alarming lives on ECS MemoryUtilization). The ASG name
+    // CloudWatch Agent is installed. disk_used_percent feeds the disk WARN
+    // alarm (trajectory) and disk_free_gib the disk CRITICAL alarm (imminent
+    // breakage — merges need free bytes, not free percent, so the paging signal
+    // is absolute and the warn one is not); mem_used_percent is dashboards-only
+    // (the CWAgent memory alarm is retired — memory alarming lives on ECS
+    // MemoryUtilization). Free space is read in MiB and divided rather than
+    // taken from `--block-size=1G`, whose integer truncation would quantise the
+    // metric to 1 GiB steps against a floor measured in tens. The ASG name
     // (the alarms' dimension) is unknowable at synth (LaunchTemplate → ASG is a
     // CFN cycle), so it resolves at run time: IMDS instance tags first, with a
     // describe-auto-scaling-instances fallback. AL2023 ECS AMIs ship no cron;
@@ -375,10 +380,10 @@ chmod 644 "$MOUNT_POINT/server-certs/client.xml"
     // timer never re-triggers a still-activating unit, so ONE wedged run (hung
     // IMDS or AWS call) would silence the publisher forever — every curl carries
     // --max-time and the unit a TimeoutStartSec under the 60s cadence. The disk
-    // metric publishes only when the data volume is actually mounted: `df` on
+    // metrics publish only when the data volume is actually mounted: `df` on
     // an unmounted path reports the ROOT filesystem, a false-healthy number
     // that would defeat the disk-critical alarm's missing-data=BREACHING flip.
-    const { namespace, memoryMetric, diskMetric, asgDimension } = CLICKHOUSE_HOST_METRICS;
+    const { namespace, memoryMetric, diskMetric, diskFreeMetric, asgDimension } = CLICKHOUSE_HOST_METRICS;
     const metricsPublisher = `
 cat > /usr/local/bin/fjall-ch-metrics.sh << 'METRICSEOF'
 #!/bin/bash
@@ -401,8 +406,10 @@ METRICS=("MetricName=${memoryMetric},Dimensions=[{Name=${asgDimension},Value=$AS
 if mountpoint -q ${CLICKHOUSE_DATA_MOUNT_PATH}; then
   DISK=$(df --output=pcent ${CLICKHOUSE_DATA_MOUNT_PATH} | tail -n 1 | tr -dc '0-9')
   METRICS+=("MetricName=${diskMetric},Dimensions=[{Name=${asgDimension},Value=$ASG}],Value=$DISK,Unit=Percent")
+  FREE=$(df --output=avail --block-size=1M ${CLICKHOUSE_DATA_MOUNT_PATH} | tail -n 1 | tr -dc '0-9' | awk '{printf "%.2f", $1/1024}')
+  METRICS+=("MetricName=${diskFreeMetric},Dimensions=[{Name=${asgDimension},Value=$ASG}],Value=$FREE,Unit=Gigabytes")
 else
-  echo "fjall-ch-metrics: ${CLICKHOUSE_DATA_MOUNT_PATH} not mounted, skipping disk metric" >&2
+  echo "fjall-ch-metrics: ${CLICKHOUSE_DATA_MOUNT_PATH} not mounted, skipping disk metrics" >&2
 fi
 aws cloudwatch put-metric-data --region "$REGION" --namespace ${namespace} --metric-data "\${METRICS[@]}"
 METRICSEOF
@@ -490,6 +497,15 @@ fi
 mkdir -p "$MOUNT_POINT"
 mount "$DEVICE" "$MOUNT_POINT"
 
+# The declared size below is load-bearing, and it MUST be a statement, not a
+# comment — compactUserDataScript strips comments from the emitted script.
+# User data is part of the launch template, so the size appearing verbatim in
+# the emitted script is what turns a storageGb change into a new template
+# version -> instance refresh -> the boot-time resize2fs below. Without it a
+# volume increase never relaunches anything and the grown capacity stays
+# unusable until an unrelated deploy replaces the instance.
+DECLARED_DATA_VOLUME_GIB=${options.dataVolumeSizeGb}
+#
 # Grow the filesystem to fill the volume. Raising the CDK volume size issues a
 # ModifyVolume against the block device only — ext4 keeps its old size until
 # resize2fs runs, so without this line every capacity increase is INERT and the

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

@@ -1,15 +1,36 @@
 function camelToSnakeCase(input) {
     return input.replace(/[A-Z]/g, (m) => "_" + m.toLowerCase());
 }
+function renderConstraintsBlock(constraints) {
+    const settings = Object.entries(constraints).map(([key, constraint]) => {
+        const xmlName = camelToSnakeCase(key);
+        const children = [];
+        if (constraint.min !== undefined) {
+            children.push(`                    <min>${String(constraint.min)}</min>`);
+        }
+        if (constraint.max !== undefined) {
+            children.push(`                    <max>${String(constraint.max)}</max>`);
+        }
+        if (constraint.readonly === true) {
+            children.push(`                    <readonly/>`);
+        }
+        return `                <${xmlName}>\n${children.join("\n")}\n                </${xmlName}>`;
+    });
+    return `            <constraints>\n${settings.join("\n")}\n            </constraints>`;
+}
 function renderProfileSpec(spec) {
+    const { constraints, ...scalars } = spec;
     const lines = [];
-    for (const [key, value] of Object.entries(spec)) {
+    for (const [key, value] of Object.entries(scalars)) {
         if (value === undefined)
             continue;
         const xmlName = camelToSnakeCase(key);
         const xmlValue = typeof value === "boolean" ? (value ? "1" : "0") : String(value);
         lines.push(`            <${xmlName}>${xmlValue}</${xmlName}>`);
     }
+    if (constraints !== undefined && Object.keys(constraints).length > 0) {
+        lines.push(renderConstraintsBlock(constraints));
+    }
     return lines.join("\n");
 }
 function renderDefaultUserBlock(access) {

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

@@ -23,10 +23,39 @@ export interface ClickHouseAlarmThresholds {
      *  CWAgent host-memory alarm is retired (its threshold meant a different
      *  headroom per instance size; the timer metric remains for dashboards). */
     memoryThreshold?: number;
-    /** ClickHouse data volume disk % used. Default 70 (warn) — paired with critical at 85. */
+    /** ClickHouse data volume disk % used. Default 70. The TRAJECTORY signal —
+     *  "this volume is filling up, plan growth" — which is the one disk
+     *  question a percentage answers well at any volume size. The imminent-
+     *  breakage question is answered in GiB by `diskFreeCriticalGib`.
+     *
+     *  The nightly restore-verify transiently doubles the database's on-disk
+     *  footprint, so a database above ~35 % of the volume crosses a 70 % warn
+     *  during every verify window. That is the knob's honest reading — the
+     *  volume genuinely is that full while the scratch copy exists — but when
+     *  the nightly warn becomes noise, the cures are a larger `storageGb`, a
+     *  higher threshold here, or `backupVerify: false`; the critical floor is
+     *  protected from the same transient by the verify gate's ×2 margin. */
     diskWarnThreshold?: number;
-    /** ClickHouse data volume disk % used. Default 85. */
-    diskCriticalThreshold?: number;
+    /** Free space on the ClickHouse data volume, in GiB, below which the
+     *  critical alarm pages. Defaults to `defaultDiskFreeCriticalGib(storageGb)`
+     *  — the larger of an absolute floor and a share of the volume.
+     *
+     *  Absolute rather than a percentage BECAUSE the failure it guards is
+     *  absolute: a merge needs free bytes proportional to the parts it is
+     *  merging, not to the volume, and the server stops accepting inserts on a
+     *  fixed reserve. A percentage critical was either redundant (on a small
+     *  volume the free-space floor is crossed first) or noise (on a large one
+     *  85 % used still leaves hundreds of usable GiB) — never uniquely useful.
+     *
+     *  Must stay under a fifth of `storageGb`, so the floor is a slice of the
+     *  disk rather than most of it; `resolveClickHouseStorage` enforces the
+     *  pair together, since neither value is checkable alone.
+     *
+     *  Replaces `diskCriticalThreshold` (a percentage of the volume used). The
+     *  rename carries a unit change, so there is no value that means the same
+     *  thing in both — a declaration on the old key fails to compile rather
+     *  than deploying a threshold read as the wrong quantity. */
+    diskFreeCriticalGib?: number;
     /** `<Error>`/`<Fatal>` server-log lines per 5 min. Default 30. */
     serverErrorsPer5Min?: number;
     /** Failed `executeQuery:` error lines per 5 min. Default 10 — absolute, not
@@ -52,7 +81,7 @@ export interface ClickHouseAlarmThresholds {
  * backup heartbeat window. The remaining fields are consumed by the pattern's
  * service-alarm and logAlarms wiring (see `ClickHouseAlarmThresholds`).
  */
-export type ClickHouseHostAlarmThresholds = Pick<ClickHouseAlarmThresholds, "cpuThreshold" | "diskWarnThreshold" | "diskCriticalThreshold" | "backupHeartbeatWindowHours">;
+export type ClickHouseHostAlarmThresholds = Pick<ClickHouseAlarmThresholds, "cpuThreshold" | "diskWarnThreshold" | "backupHeartbeatWindowHours">;
 export declare const BACKUP_HEARTBEAT_DEFAULT_WINDOW_HOURS = 26;
 /**
  * Ceiling derivation — an ORDERING bound, not CloudWatch expressibility.
@@ -97,7 +126,25 @@ export interface ClickHouseAlarmsProps {
      * Omitted when `backupSchedule: false` — no backup task, no log group.
      */
     backupTaskLogGroup?: ILogGroup;
+    /**
+     * Whether the backup task runs the restore-verify (the pattern's
+     * `backupVerify` prop, already resolved). `false` withholds the two verify
+     * alarms so a deliberately disabled verify never leaves marker-counting
+     * alarms armed against a script that emits no markers — the alarm half and
+     * the script half of the contract disable together. The backup-failure
+     * alarm and the success heartbeat stay: they monitor the backup itself.
+     */
+    backupVerifyEnabled?: boolean;
     config?: ClickHouseHostAlarmThresholds;
+    /**
+     * Critical free-space floor in GiB, ALREADY RESOLVED. Not read off `config`
+     * because its default depends on the volume size and its legality depends
+     * on the volume size — both of which live on the pattern, not here. The
+     * pattern resolves the pair once (`resolveClickHouseStorage`) and hands the
+     * answer down; re-deriving it here would be a second source for a number
+     * that must agree with the volume it guards.
+     */
+    diskFreeCriticalGib: number;
     /** Application ID for webhook-to-application alarm mapping. */
     applicationId?: string;
 }
@@ -107,7 +154,9 @@ export interface ClickHouseAlarmsProps {
  * (never installed on these hosts) but by the lightweight put-metric-data
  * timer the user-data installs (see `buildClickHouseUserData`), which publishes
  * `mem_used_percent` / `disk_used_percent` under the same names and
- * `AutoScalingGroupName` dimension the agent would use — plus the
+ * `AutoScalingGroupName` dimension the agent would use, plus `disk_free_gib`,
+ * which has no CloudWatch Agent equivalent and exists because the disk
+ * question that pages must be answered in bytes rather than percent — plus the
  * backup-failure log alarm when a backup-task log group is supplied:
  *
  * - **Backup failures** — `AccessDenied` or `S3Exception` from the backup