@intentius/chant-lexicon-cpln 0.53.0

package/src/lint/post-synth/cpl012-no-literal-credential-env.ts

@@ -0,0 +1,58 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readString } from "../../entity-props";
+import { WORKLOAD, entitiesOfType } from "./helpers";
+
+/** `cpln://secret/NAME.FIELD` — the field qualifier is the part that matters. */
+const SECRET_REF = /^cpln:\/\/secret\/([^/.\s]+)(?:\.([^/\s]+))?$/;
+
+/** Env var names that read as credentials. */
+const CREDENTIAL_NAME = /(password|passwd|secret|token|apikey|api_key|access_key|private_key|credential)/i;
+
+/**
+ * Values that look like a deliberate non-secret rather than a leaked one: an
+ * empty string, an obvious placeholder, or another `cpln://` reference.
+ */
+const PLACEHOLDER = /^(|changeme|placeholder|todo|xxx+|\*+|<[^>]*>|\$\{[^}]*\})$/i;
+
+/**
+ * CPL012: a credential-shaped env var carrying a literal value.
+ *
+ * The alternative is one string change — `cpln://secret/db.password` — so a
+ * literal here is almost always an oversight rather than a decision. Env values
+ * end up in the workload spec, which is readable by anyone with `get` on the
+ * workload, and in every diff of the manifest.
+ */
+export const noLiteralCredentialEnvCheck: PostSynthCheck = {
+  id: "CPL012",
+  description: "Credential-shaped environment variables must reference a secret, not a literal",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      for (const container of readArray(entity, "spec", "containers")) {
+        const containerName = readString(container, "name") ?? "?";
+        for (const env of readArray(container, "env")) {
+          const envName = readString(env, "name");
+          const value = readString(env, "value");
+          if (!envName || value === undefined) continue;
+          if (!CREDENTIAL_NAME.test(envName)) continue;
+          if (value.startsWith("cpln://") || PLACEHOLDER.test(value)) continue;
+
+          diagnostics.push({
+            checkId: "CPL012",
+            severity: "error",
+            message:
+              `Workload "${name}" container "${containerName}" sets env "${envName}" to a literal value. ` +
+              `Reference a secret instead — \`cpln://secret/NAME.FIELD\` — so the value is not stored in ` +
+              `the workload spec or its diffs.`,
+            entity: name,
+            lexicon: "cpln",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/cpl013-qualified-identity-principal.ts

@@ -0,0 +1,45 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { propsOf, readArray } from "../../entity-props";
+import { GVC, POLICY, entitiesOfType } from "./helpers";
+
+/**
+ * CPL013: an identity principal link that Control Plane will ignore.
+ *
+ * `//identity/NAME` is accepted by the policy API and then has no effect. Only
+ * the GVC-qualified `//gvc/GVC/identity/NAME` grants anything. Nothing reports
+ * this — the policy exists, the binding exists, and the permission is simply
+ * never granted.
+ */
+export const qualifiedIdentityPrincipalCheck: PostSynthCheck = {
+  id: "CPL013",
+  description: "Policy bindings must name identities by their GVC-qualified link",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, POLICY)) {
+      for (const binding of readArray(entity, "bindings")) {
+        const links = propsOf(binding).principalLinks;
+        if (!Array.isArray(links)) continue;
+
+        for (const link of links) {
+          if (typeof link !== "string") continue;
+          if (!/^\/\/identity\/[^/]+$/.test(link)) continue;
+
+          diagnostics.push({
+            checkId: "CPL013",
+            severity: "error",
+            message:
+              `Policy "${name}" binds the principal "${link}". Control Plane silently ignores the bare ` +
+              `//identity/NAME form — use //gvc/<gvc>/identity/${link.slice("//identity/".length)} instead. ` +
+              `The policy will apply cleanly and grant nothing as written.`,
+            entity: name,
+            lexicon: "cpln",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/cpl014-qualified-secret-ref.ts

@@ -0,0 +1,54 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readString } from "../../entity-props";
+import { WORKLOAD, entitiesOfType } from "./helpers";
+
+/** `cpln://secret/NAME.FIELD` — the field qualifier is the part that matters. */
+const SECRET_REF = /^cpln:\/\/secret\/([^/.\s]+)(?:\.([^/\s]+))?$/;
+
+/**
+ * CPL014: a secret reference with no field qualifier.
+ *
+ * `cpln://secret/db` resolves to nothing for every secret type except `gcp`,
+ * which is conventionally mounted as a whole JSON file. The field name is not
+ * optional: `opaque` needs `.payload`, `userpass` needs `.username`/`.password`,
+ * `tls` needs `.cert`/`.key`, and a `dictionary` needs one of its keys.
+ *
+ * Volume mounts are exempt — mounting a secret as a directory is the documented
+ * way to consume a `dictionary` or a `gcp` credential file.
+ */
+export const qualifiedSecretRefCheck: PostSynthCheck = {
+  id: "CPL014",
+  description: "Secret references in environment variables must name a field",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      for (const container of readArray(entity, "spec", "containers")) {
+        const containerName = readString(container, "name") ?? "?";
+        for (const env of readArray(container, "env")) {
+          const envName = readString(env, "name") ?? "?";
+          const value = readString(env, "value");
+          if (!value) continue;
+
+          const match = SECRET_REF.exec(value);
+          if (!match || match[2]) continue;
+
+          diagnostics.push({
+            checkId: "CPL014",
+            severity: "error",
+            message:
+              `Workload "${name}" container "${containerName}" sets env "${envName}" to "${value}", which ` +
+              `names no field. Use \`cpln://secret/${match[1]}.FIELD\` — \`.payload\` for opaque, ` +
+              `\`.username\`/\`.password\` for userpass, \`.cert\`/\`.key\` for tls, a key name for a ` +
+              `dictionary. An unqualified reference resolves to nothing at runtime.`,
+            entity: name,
+            lexicon: "cpln",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/cpl020-serverless-single-port.ts

@@ -0,0 +1,58 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readString } from "../../entity-props";
+import { WORKLOAD, entitiesOfType, exposedPorts, workloadType } from "./helpers";
+
+/**
+ * CPL020: a serverless workload must expose exactly one HTTP port.
+ *
+ * Not "at least one" and not "any number" — exactly one, and it must be HTTP.
+ * Zero is the more common mistake and the more confusing one, because the
+ * workload deploys and reports healthy while serving nothing.
+ */
+export const serverlessSinglePortCheck: PostSynthCheck = {
+  id: "CPL020",
+  description: "Serverless workloads must expose exactly one HTTP port",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      if (workloadType(entity) !== "serverless") continue;
+
+      const ports = exposedPorts(entity);
+      if (ports.length !== 1) {
+        diagnostics.push({
+          checkId: "CPL020",
+          severity: "error",
+          message:
+            `Serverless workload "${name}" exposes ${ports.length} ports; exactly one HTTP port is required. ` +
+            (ports.length === 0
+              ? `It will deploy and serve nothing.`
+              : `Use a standard workload if it genuinely needs several.`),
+          entity: name,
+          lexicon: "cpln",
+        });
+        continue;
+      }
+
+      // The single port must be HTTP. `tcp` and `grpc` need a standard workload.
+      for (const container of readArray(entity, "spec", "containers")) {
+        for (const port of readArray(container, "ports")) {
+          const protocol = readString(port, "protocol") ?? "http";
+          if (protocol === "http" || protocol === "http2") continue;
+          diagnostics.push({
+            checkId: "CPL020",
+            severity: "error",
+            message:
+              `Serverless workload "${name}" exposes a "${protocol}" port. Serverless supports only http ` +
+              `and http2 — use a standard workload for ${protocol}.`,
+            entity: name,
+            lexicon: "cpln",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/cpl021-cron-job-shape.ts

@@ -0,0 +1,64 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readPath, readString } from "../../entity-props";
+import { WORKLOAD, entitiesOfType, exposedPorts, workloadType } from "./helpers";
+
+/**
+ * CPL021: a cron workload needs a schedule and must expose no ports.
+ *
+ * Cron cannot serve traffic, so a port on one is always a misunderstanding —
+ * usually a workload converted from serverless with the ports left behind. A
+ * missing `spec.job.schedule` is the other half: `spec.job` is *required* for
+ * cron and forbidden for every other type.
+ */
+export const cronJobShapeCheck: PostSynthCheck = {
+  id: "CPL021",
+  description: "Cron workloads must declare a schedule and expose no ports",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      const type = workloadType(entity);
+      const job = readPath(entity, "spec", "job");
+      const schedule = readString(entity, "spec", "job", "schedule");
+
+      if (type === "cron") {
+        if (!schedule) {
+          diagnostics.push({
+            checkId: "CPL021",
+            severity: "error",
+            message: `Cron workload "${name}" has no spec.job.schedule. A cron workload requires one.`,
+            entity: name,
+            lexicon: "cpln",
+          });
+        }
+
+        const ports = exposedPorts(entity);
+        if (ports.length > 0) {
+          diagnostics.push({
+            checkId: "CPL021",
+            severity: "error",
+            message:
+              `Cron workload "${name}" exposes ${ports.length} port(s) (${ports.join(", ")}). Cron workloads ` +
+              `cannot serve traffic — remove the ports, or use a standard workload.`,
+            entity: name,
+            lexicon: "cpln",
+          });
+        }
+        continue;
+      }
+
+      if (job !== undefined) {
+        diagnostics.push({
+          checkId: "CPL021",
+          severity: "error",
+          message: `Workload "${name}" is type "${type}" but sets spec.job. Only cron workloads may declare one.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/cpl022-container-ports.ts

@@ -0,0 +1,64 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readNumber, readString } from "../../entity-props";
+import { WORKLOAD, entitiesOfType } from "./helpers";
+
+/**
+ * CPL022: `port` and `ports` are mutually exclusive, and port numbers must be
+ * unique across every container in a workload.
+ *
+ * The duplicate case is the one worth catching: two containers each binding
+ * 8080 is accepted at author time, rejected at apply, and reads as correct.
+ */
+export const containerPortsCheck: PostSynthCheck = {
+  id: "CPL022",
+  description: "Container ports must not mix `port` and `ports`, and must be unique across containers",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      const seen = new Map<number, string>();
+
+      for (const container of readArray(entity, "spec", "containers")) {
+        const containerName = readString(container, "name") ?? "?";
+        const single = readNumber(container, "port");
+        const list = readArray(container, "ports");
+
+        if (single !== undefined && list.length > 0) {
+          diagnostics.push({
+            checkId: "CPL022",
+            severity: "error",
+            message:
+              `Workload "${name}" container "${containerName}" sets both \`port\` and \`ports\`. ` +
+              `They are mutually exclusive — keep \`ports\`.`,
+            entity: name,
+            lexicon: "cpln",
+          });
+        }
+
+        const numbers = [
+          ...(single !== undefined ? [single] : []),
+          ...list.map((port) => readNumber(port, "number")).filter((n): n is number => n !== undefined),
+        ];
+
+        for (const number of numbers) {
+          const owner = seen.get(number);
+          if (owner !== undefined && owner !== containerName) {
+            diagnostics.push({
+              checkId: "CPL022",
+              severity: "error",
+              message:
+                `Workload "${name}" exposes port ${number} from both "${owner}" and "${containerName}". ` +
+                `Port numbers must be unique across the containers of one workload.`,
+              entity: name,
+              lexicon: "cpln",
+            });
+          }
+          seen.set(number, containerName);
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/cpl023-container-resources.ts

@@ -0,0 +1,87 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { propsOf, readArray, readString } from "../../entity-props";
+import { WORKLOAD, entitiesOfType, parseCpuMillicores, parseMemoryMib } from "./helpers";
+
+/** The tag that raises the memory-to-CPU ceiling from 8 to 32. */
+const RELAX_RATIO_TAG = "cpln/relaxMemoryToCpuRatio";
+
+const CPU_MIN_MILLICORES = 25;
+const MEMORY_MIN_MIB = 32;
+const RATIO_MAX = 8;
+const RATIO_MAX_RELAXED = 32;
+
+/**
+ * CPL023: CPU and memory floors, and the memory-to-CPU ratio.
+ *
+ * The ratio is the non-obvious one. `memory(MiB) / cpu(millicores)` must be
+ * ≤ 8, so `2Gi` of memory needs at least 256 millicores of CPU — a workload
+ * asking for lots of memory and a little CPU is rejected, which surprises
+ * people coming from Kubernetes where the two are independent. The
+ * `cpln/relaxMemoryToCpuRatio` tag raises the ceiling to 32.
+ */
+export const containerResourcesCheck: PostSynthCheck = {
+  id: "CPL023",
+  description: "Container CPU and memory must clear the platform floors and the memory-to-CPU ratio",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      const tags = propsOf(entity).tags;
+      const relaxed = !!tags && typeof tags === "object" && RELAX_RATIO_TAG in (tags as Record<string, unknown>);
+      const ceiling = relaxed ? RATIO_MAX_RELAXED : RATIO_MAX;
+
+      for (const container of readArray(entity, "spec", "containers")) {
+        const containerName = readString(container, "name") ?? "?";
+        // Control Plane's defaults, so an omitted value is checked as what it
+        // will actually become rather than skipped.
+        const cpu = parseCpuMillicores(readString(container, "cpu") ?? "50m");
+        const memory = parseMemoryMib(readString(container, "memory") ?? "128Mi");
+
+        if (cpu !== undefined && cpu < CPU_MIN_MILLICORES) {
+          diagnostics.push({
+            checkId: "CPL023",
+            severity: "error",
+            message:
+              `Workload "${name}" container "${containerName}" requests ${cpu}m CPU; the minimum is ` +
+              `${CPU_MIN_MILLICORES}m.`,
+            entity: name,
+            lexicon: "cpln",
+          });
+        }
+
+        if (memory !== undefined && memory < MEMORY_MIN_MIB) {
+          diagnostics.push({
+            checkId: "CPL023",
+            severity: "error",
+            message:
+              `Workload "${name}" container "${containerName}" requests ${Math.round(memory)}Mi memory; ` +
+              `the minimum is ${MEMORY_MIN_MIB}Mi.`,
+            entity: name,
+            lexicon: "cpln",
+          });
+        }
+
+        if (cpu !== undefined && memory !== undefined && cpu > 0) {
+          const ratio = memory / cpu;
+          if (ratio > ceiling) {
+            const needed = Math.ceil(memory / ceiling);
+            diagnostics.push({
+              checkId: "CPL023",
+              severity: "error",
+              message:
+                `Workload "${name}" container "${containerName}" has a memory-to-CPU ratio of ` +
+                `${ratio.toFixed(1)} (${Math.round(memory)}Mi / ${cpu}m), above the limit of ${ceiling}. ` +
+                `Raise CPU to at least ${needed}m` +
+                (relaxed ? "." : `, or add the \`${RELAX_RATIO_TAG}\` tag to raise the ceiling to ${RATIO_MAX_RELAXED}.`),
+              entity: name,
+              lexicon: "cpln",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/cpl024-probe-handler.ts

@@ -0,0 +1,51 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readPath, readString } from "../../entity-props";
+import { WORKLOAD, entitiesOfType } from "./helpers";
+
+/** The four mutually exclusive probe handlers. */
+const PROBE_HANDLERS = ["exec", "grpc", "tcpSocket", "httpGet"] as const;
+
+/**
+ * CPL024: a probe must set exactly one handler.
+ *
+ * Zero is the interesting case: a `readinessProbe` with only
+ * `initialDelaySeconds` and `periodSeconds` set looks configured and probes
+ * nothing.
+ */
+export const probeHandlerCheck: PostSynthCheck = {
+  id: "CPL024",
+  description: "Each health-check probe must set exactly one of exec, grpc, tcpSocket, httpGet",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      for (const container of readArray(entity, "spec", "containers")) {
+        const containerName = readString(container, "name") ?? "?";
+
+        for (const probeName of ["readinessProbe", "livenessProbe"]) {
+          const probe = readPath(container, probeName);
+          if (!probe || typeof probe !== "object") continue;
+
+          const set = PROBE_HANDLERS.filter((handler) => readPath(probe, handler) !== undefined);
+          if (set.length === 1) continue;
+
+          diagnostics.push({
+            checkId: "CPL024",
+            severity: "error",
+            message:
+              set.length === 0
+                ? `Workload "${name}" container "${containerName}" declares a ${probeName} with no handler. ` +
+                  `Set exactly one of ${PROBE_HANDLERS.join(", ")} — as written the probe checks nothing.`
+                : `Workload "${name}" container "${containerName}" ${probeName} sets ${set.length} handlers ` +
+                  `(${set.join(", ")}). They are mutually exclusive; keep one.`,
+            entity: name,
+            lexicon: "cpln",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/cpl025-autoscaling-shape.ts

@@ -0,0 +1,100 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readNumber, readString } from "../../entity-props";
+import { WORKLOAD, autoscalingOf, entitiesOfType, workloadType } from "./helpers";
+
+/** Which strategies each workload type supports at all. */
+const SUPPORTED_METRICS: Record<string, string[]> = {
+  serverless: ["concurrency", "rps", "cpu", "memory", "disabled"],
+  standard: ["rps", "cpu", "memory", "latency", "keda", "disabled"],
+  stateful: ["rps", "cpu", "memory", "latency", "keda", "disabled"],
+};
+
+/**
+ * CPL025: mutually exclusive autoscaling fields, and the `target` ceiling.
+ *
+ * `metric` and `multi` are alternatives, not layers; `target` belongs to the
+ * single-metric form and is rejected alongside `multi`; and with cpu or memory
+ * as the metric, `target` is a utilization percentage, so above 100 it is not
+ * an aggressive setting but an invalid one.
+ */
+export const autoscalingShapeCheck: PostSynthCheck = {
+  id: "CPL025",
+  description: "Autoscaling `metric`, `multi` and `target` must form a valid combination",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      const scaling = autoscalingOf(entity);
+      if (!scaling || typeof scaling !== "object") continue;
+
+      const metric = readString(scaling, "metric");
+      const multi = readArray(scaling, "multi");
+      const target = readNumber(scaling, "target");
+      const type = workloadType(entity);
+
+      if (metric && multi.length > 0) {
+        diagnostics.push({
+          checkId: "CPL025",
+          severity: "error",
+          message:
+            `Workload "${name}" sets both autoscaling.metric ("${metric}") and autoscaling.multi. ` +
+            `They are mutually exclusive — multi is the multi-metric form and replaces metric.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      if (target !== undefined && multi.length > 0) {
+        diagnostics.push({
+          checkId: "CPL025",
+          severity: "error",
+          message:
+            `Workload "${name}" sets autoscaling.target alongside autoscaling.multi. ` +
+            `Each entry in multi carries its own target.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      if (target !== undefined && (metric === "cpu" || metric === "memory") && target > 100) {
+        diagnostics.push({
+          checkId: "CPL025",
+          severity: "error",
+          message:
+            `Workload "${name}" sets autoscaling.target ${target} with metric "${metric}", which is a ` +
+            `utilization percentage capped at 100.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      const supported = SUPPORTED_METRICS[type];
+      if (metric && supported && !supported.includes(metric)) {
+        diagnostics.push({
+          checkId: "CPL025",
+          severity: "error",
+          message:
+            `Workload "${name}" is type "${type}" and uses autoscaling metric "${metric}", which that type ` +
+            `does not support. Available: ${supported.join(", ")}.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      if (multi.length > 0 && type === "serverless") {
+        diagnostics.push({
+          checkId: "CPL025",
+          severity: "error",
+          message:
+            `Workload "${name}" is serverless and uses multi-metric autoscaling, which is available only ` +
+            `on standard and stateful workloads.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/cpl026-scale-to-zero.ts

@@ -0,0 +1,67 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readNumber, readPath, readString } from "../../entity-props";
+import { WORKLOAD, autoscalingOf, entitiesOfType, workloadType } from "./helpers";
+
+/** Strategies that let a workload scale to zero, by workload type. */
+const SCALE_TO_ZERO: Record<string, string[]> = {
+  serverless: ["rps", "concurrency"],
+  standard: ["keda"],
+  stateful: ["keda"],
+};
+
+/**
+ * CPL026: scale-to-zero that will not happen.
+ *
+ * `minScale: 0` is accepted on any workload type. It only *takes effect* for
+ * serverless with `rps` or `concurrency`, or for standard/stateful under KEDA.
+ * Everywhere else the workload holds at one replica and the cost saving that
+ * motivated the setting never arrives — with nothing reported.
+ */
+export const scaleToZeroCheck: PostSynthCheck = {
+  id: "CPL026",
+  description: "minScale 0 must pair with a strategy that can actually scale to zero",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      const scaling = autoscalingOf(entity);
+      if (!scaling || typeof scaling !== "object") continue;
+      if (readNumber(scaling, "minScale") !== 0) continue;
+
+      const type = workloadType(entity);
+      const metric = readString(scaling, "metric") ?? (type === "serverless" ? "concurrency" : undefined);
+
+      if (type === "cron") {
+        diagnostics.push({
+          checkId: "CPL026",
+          severity: "error",
+          message: `Cron workload "${name}" sets minScale 0. Cron workloads cannot scale to zero.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+        continue;
+      }
+
+      const allowed = SCALE_TO_ZERO[type] ?? [];
+      const usingKeda = metric === "keda" || readPath(scaling, "keda") !== undefined;
+      if (allowed.includes(metric ?? "") || (allowed.includes("keda") && usingKeda)) continue;
+
+      diagnostics.push({
+        checkId: "CPL026",
+        severity: "warning",
+        message:
+          `Workload "${name}" (type "${type}") sets minScale 0 with metric "${metric ?? "unset"}", which ` +
+          `cannot scale to zero. ` +
+          (type === "serverless"
+            ? `Serverless scales to zero only with "rps" or "concurrency".`
+            : `Standard and stateful workloads scale to zero only under KEDA, which must be enabled on the GVC.`) +
+          ` As written the workload holds at one replica with no error.`,
+        entity: name,
+        lexicon: "cpln",
+      });
+    }
+
+    return diagnostics;
+  },
+};