@intentius/chant-lexicon-cpln 0.53.0

package/src/lint/post-synth/cpl027-capacity-ai-conflict.ts

@@ -0,0 +1,78 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readBoolean, readPath, readString } from "../../entity-props";
+import { WORKLOAD, autoscalingOf, entitiesOfType, workloadType } from "./helpers";
+
+/**
+ * CPL027: Capacity AI combined with something it excludes.
+ *
+ * Capacity AI resizes CPU and memory from observed usage, and it is **on by
+ * default** for serverless, standard and cron — so these conflicts are usually
+ * reached by adding CPU autoscaling or a GPU to a workload that never opted
+ * into Capacity AI in the first place. Each conflict has the same root: the
+ * other feature needs a stable resource baseline that Capacity AI is actively
+ * moving.
+ */
+export const capacityAiConflictCheck: PostSynthCheck = {
+  id: "CPL027",
+  description: "Capacity AI conflicts with CPU-utilization autoscaling, multi-metric autoscaling and GPUs",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      const type = workloadType(entity);
+      // Default-on for every type except stateful, so `undefined` means enabled
+      // for those — which is exactly how these conflicts get reached unnoticed.
+      const declared = readBoolean(entity, "spec", "defaultOptions", "capacityAI");
+      const enabled = declared ?? type !== "stateful";
+      if (!enabled) continue;
+
+      const implicit = declared === undefined;
+      const how = implicit ? "Capacity AI is on by default for this workload type and" : "Capacity AI";
+
+      const scaling = autoscalingOf(entity);
+      const metric = scaling && typeof scaling === "object" ? readString(scaling, "metric") : undefined;
+      const multi = scaling && typeof scaling === "object" ? readArray(scaling, "multi") : [];
+
+      if (metric === "cpu") {
+        diagnostics.push({
+          checkId: "CPL027",
+          severity: "error",
+          message:
+            `Workload "${name}": ${how} conflicts with CPU-utilization autoscaling — dynamic CPU allocation ` +
+            `moves the baseline the metric scales against. Set defaultOptions.capacityAI false, or scale on ` +
+            `rps or memory.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      if (multi.length > 0) {
+        diagnostics.push({
+          checkId: "CPL027",
+          severity: "error",
+          message:
+            `Workload "${name}": ${how} conflicts with multi-metric autoscaling, which requires stable ` +
+            `resource baselines. Set defaultOptions.capacityAI false.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      for (const container of readArray(entity, "spec", "containers")) {
+        if (readPath(container, "gpu") === undefined) continue;
+        diagnostics.push({
+          checkId: "CPL027",
+          severity: "error",
+          message:
+            `Workload "${name}" container "${readString(container, "name") ?? "?"}" requests a GPU, and ` +
+            `${how} conflicts with it — GPU allocation is fixed. Set defaultOptions.capacityAI false.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/cpl028-volume-set.ts

@@ -0,0 +1,183 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readNumber, readString } from "../../entity-props";
+import { GVC, VOLUMESET, WORKLOAD, entitiesOfType } from "./helpers";
+
+/** Minimum initial capacity in GB, by performance class. */
+const MIN_CAPACITY_GB: Record<string, number> = {
+  "general-purpose-ssd": 10,
+  "high-throughput-ssd": 200,
+  shared: 10,
+};
+
+const MAX_CAPACITY_GB = 65_536;
+
+/** Filesystems that bind to exactly one stateful workload. */
+const EXCLUSIVE_FILESYSTEMS = new Set(["ext4", "xfs"]);
+
+/** Control Plane caps a workload at 15 volumes. */
+const MAX_VOLUMES = 15;
+
+const VOLUMESET_URI = /^cpln:\/\/volumeset\/(.+)$/;
+
+export const volumeSetCheck: PostSynthCheck = {
+  id: "CPL028",
+  description: "Volume set capacity, filesystem binding, and workload mount rules",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    // Volume sets by their declared name, so a mount can be checked against the
+    // set it names rather than only against itself.
+    const volumeSets = new Map<string, { entity: unknown; gvc?: string; fileSystemType: string }>();
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, VOLUMESET)) {
+      const declaredName = readString(entity, "name") ?? name;
+      const fileSystemType = readString(entity, "spec", "fileSystemType") ?? "ext4";
+      volumeSets.set(declaredName, { entity, gvc: readString(entity, "gvc"), fileSystemType });
+
+      const performanceClass =
+        readString(entity, "spec", "performanceClass") ?? (fileSystemType === "shared" ? "shared" : "general-purpose-ssd");
+      const capacity = readNumber(entity, "spec", "initialCapacity");
+
+      const floor = MIN_CAPACITY_GB[performanceClass];
+      if (capacity !== undefined && floor !== undefined && capacity < floor) {
+        diagnostics.push({
+          checkId: "CPL028",
+          severity: "error",
+          message:
+            `Volume set "${name}" requests ${capacity} GB with performanceClass "${performanceClass}", ` +
+            `below its ${floor} GB minimum. performanceClass is immutable after creation, so correcting ` +
+            `this later means recreating the volume set and losing its data.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      if (capacity !== undefined && capacity > MAX_CAPACITY_GB) {
+        diagnostics.push({
+          checkId: "CPL028",
+          severity: "error",
+          message: `Volume set "${name}" requests ${capacity} GB, above the ${MAX_CAPACITY_GB} GB maximum.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      if (fileSystemType === "shared" && performanceClass !== "shared") {
+        diagnostics.push({
+          checkId: "CPL028",
+          severity: "warning",
+          message:
+            `Volume set "${name}" has fileSystemType "shared" but performanceClass "${performanceClass}". ` +
+            `Control Plane forces "shared" for a shared filesystem, so the declared value will not match ` +
+            `what comes back and will read as drift on every plan.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      // Custom encryption is AWS KMS on a block device; a shared filesystem has
+      // no device to encrypt.
+      if (fileSystemType === "shared" && readString(entity, "spec", "customEncryption", "secretLink")) {
+        diagnostics.push({
+          checkId: "CPL028",
+          severity: "error",
+          message: `Volume set "${name}" sets customEncryption with fileSystemType "shared"; it is supported on ext4 and xfs only.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+    }
+
+    for (const [name, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      const type = readString(entity, "spec", "type") ?? "serverless";
+      const workloadGvc = readString(entity, "gvc");
+      const paths: string[] = [];
+      let mountCount = 0;
+
+      for (const container of readArray(entity, "spec", "containers")) {
+        const containerName = readString(container, "name") ?? "?";
+
+        for (const volume of readArray(container, "volumes")) {
+          mountCount++;
+          const uri = readString(volume, "uri");
+          const path = readString(volume, "path");
+          if (path) paths.push(path);
+
+          const match = uri ? VOLUMESET_URI.exec(uri) : null;
+          if (!match) continue;
+
+          const target = volumeSets.get(match[1]);
+          if (!target) continue; // declared elsewhere; CPL029 covers dangling references
+
+          if (EXCLUSIVE_FILESYSTEMS.has(target.fileSystemType) && type !== "stateful") {
+            diagnostics.push({
+              checkId: "CPL028",
+              severity: "error",
+              message:
+                `Workload "${name}" is type "${type}" and container "${containerName}" mounts volume set ` +
+                `"${match[1]}", whose fileSystemType "${target.fileSystemType}" binds to exactly one ` +
+                `stateful workload. Use a "shared" volume set, or make the workload stateful.`,
+              entity: name,
+              lexicon: "cpln",
+            });
+          }
+
+          if (target.gvc && workloadGvc && target.gvc !== workloadGvc) {
+            diagnostics.push({
+              checkId: "CPL028",
+              severity: "error",
+              message:
+                `Workload "${name}" (GVC "${workloadGvc}") mounts volume set "${match[1]}" from GVC ` +
+                `"${target.gvc}". Volume sets are only mountable from within their own GVC.`,
+              entity: name,
+              lexicon: "cpln",
+            });
+          }
+        }
+      }
+
+      if (mountCount > MAX_VOLUMES) {
+        diagnostics.push({
+          checkId: "CPL028",
+          severity: "error",
+          message: `Workload "${name}" mounts ${mountCount} volumes; the maximum is ${MAX_VOLUMES}.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+
+      for (const [i, path] of paths.entries()) {
+        for (const other of paths.slice(i + 1)) {
+          if (path === other) {
+            diagnostics.push({
+              checkId: "CPL028",
+              severity: "error",
+              message: `Workload "${name}" mounts two volumes at the same path "${path}".`,
+              entity: name,
+              lexicon: "cpln",
+            });
+          } else if (isParentPath(path, other) || isParentPath(other, path)) {
+            diagnostics.push({
+              checkId: "CPL028",
+              severity: "error",
+              message:
+                `Workload "${name}" mounts volumes at "${path}" and "${other}"; no mount path may be a ` +
+                `parent of another.`,
+              entity: name,
+              lexicon: "cpln",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};
+
+/** Whether `parent` is a proper ancestor directory of `child`. */
+function isParentPath(parent: string, child: string): boolean {
+  const normalized = parent.endsWith("/") ? parent : `${parent}/`;
+  return child.startsWith(normalized);
+}

package/src/lint/post-synth/cpl029-link-targets.ts

@@ -0,0 +1,155 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { propsOf, readString } from "../../entity-props";
+import type { Declarable } from "@intentius/chant/declarable";
+import { KINDS, kindByTypeName } from "../../kinds";
+import { GVC, WORKLOAD, entitiesOfType, parseLink } from "./helpers";
+
+/**
+ * Every string anywhere in a value, so links are found wherever they were
+ * written. Depth-bounded — a spec is deep but finite, and a cycle would not be.
+ */
+function* strings(value: unknown, depth = 0): Generator<string> {
+  if (depth > 12) return;
+  if (typeof value === "string") {
+    yield value;
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) yield* strings(item, depth + 1);
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const nested of Object.values(propsOf(value))) yield* strings(nested, depth + 1);
+  }
+}
+
+/**
+ * A workload's identity must live in the workload's own GVC.
+ *
+ * Identities cannot be shared across GVCs — the documented remedy is to
+ * recreate the identity with the same spec in each GVC that needs it. A
+ * cross-GVC `identityLink` is therefore never right, however reasonable it
+ * reads.
+ */
+function identityGvcCheck(entities: Map<string, Declarable>): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [name, entity] of entitiesOfType(entities, WORKLOAD)) {
+    const workloadGvc = readString(entity, "gvc");
+    const identityLink = readString(entity, "spec", "identityLink");
+    if (!workloadGvc || !identityLink) continue;
+
+    const link = parseLink(identityLink);
+    if (!link || link.kind !== "identity" || !link.gvc) continue;
+    if (link.gvc === workloadGvc) continue;
+
+    diagnostics.push({
+      checkId: "CPL029",
+      severity: "error",
+      message:
+        `Workload "${name}" is in GVC "${workloadGvc}" but its identityLink names GVC "${link.gvc}". ` +
+        `Identities cannot be shared across GVCs — declare an identity with the same spec in ` +
+        `"${workloadGvc}".`,
+      entity: name,
+      lexicon: "cpln",
+    });
+  }
+
+  return diagnostics;
+}
+
+export const linkTargetsCheck: PostSynthCheck = {
+  id: "CPL029",
+  description: "Control Plane links must resolve to a declared resource of the right kind and GVC",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    // Declared resources by kind → name → its GVC (undefined for org-scoped).
+    const declared = new Map<string, Map<string, string | undefined>>();
+    const declaredKinds = new Set<string>();
+
+    for (const [entityName, entity] of ctx.entities) {
+      const kind = kindByTypeName(entity.entityType);
+      if (!kind) continue;
+      declaredKinds.add(kind.kind);
+      const byName = declared.get(kind.kind) ?? new Map<string, string | undefined>();
+      byName.set(readString(entity, "name") ?? entityName, readString(entity, "gvc"));
+      declared.set(kind.kind, byName);
+    }
+
+    const knownKinds = new Set(KINDS.map((k) => k.kind));
+
+    for (const [entityName, entity] of ctx.entities) {
+      const kind = kindByTypeName(entity.entityType);
+      if (!kind) continue;
+      const ownGvc = readString(entity, "gvc");
+
+      for (const value of strings(propsOf(entity))) {
+        const link = parseLink(value);
+        if (!link || !knownKinds.has(link.kind)) continue;
+
+        // Only assert against kinds this stack actually declares. Referencing a
+        // secret managed by another team is ordinary, not a defect.
+        if (!declaredKinds.has(link.kind)) continue;
+
+        const byName = declared.get(link.kind)!;
+        if (!byName.has(link.name)) {
+          diagnostics.push({
+            checkId: "CPL029",
+            severity: "warning",
+            message:
+              `${kind.kind} "${entityName}" links to "${value}", but no ${link.kind} named "${link.name}" ` +
+              `is declared in this stack. Control Plane accepts a dangling link without error.`,
+            entity: entityName,
+            lexicon: "cpln",
+          });
+          continue;
+        }
+
+        const targetGvc = byName.get(link.name);
+        if (link.gvc && targetGvc && link.gvc !== targetGvc) {
+          diagnostics.push({
+            checkId: "CPL029",
+            severity: "error",
+            message:
+              `${kind.kind} "${entityName}" links to "${value}", but ${link.kind} "${link.name}" is ` +
+              `declared in GVC "${targetGvc}".`,
+            entity: entityName,
+            lexicon: "cpln",
+          });
+        }
+      }
+    }
+
+    // A GVC-scoped resource whose GVC is declared here must name one that exists.
+    if (declaredKinds.has("gvc")) {
+      const gvcNames = new Set<string>();
+      for (const [entityName, entity] of entitiesOfType(ctx.entities, GVC)) {
+        gvcNames.add(readString(entity, "name") ?? entityName);
+      }
+
+      for (const [entityName, entity] of ctx.entities) {
+        const kind = kindByTypeName(entity.entityType);
+        if (!kind?.gvcScoped) continue;
+        const gvc = readString(entity, "gvc");
+        if (!gvc || gvcNames.has(gvc)) continue;
+
+        diagnostics.push({
+          checkId: "CPL029",
+          severity: "warning",
+          message:
+            `${kind.kind} "${entityName}" is placed in GVC "${gvc}", which this stack does not declare. ` +
+            `If the GVC is managed elsewhere this is fine; if it is a typo, the apply fails with a ` +
+            `not-found on the parent.`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+      }
+    }
+
+    diagnostics.push(...identityGvcCheck(ctx.entities));
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/cpl030-domain-routing.ts

@@ -0,0 +1,137 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readPath, readString } from "../../entity-props";
+import { DOMAIN, GVC, WORKLOAD, entitiesOfType, parseLink } from "./helpers";
+
+/** An apex domain has exactly two labels: `example.com`, not `api.example.com`. */
+function isApex(name: string): boolean {
+  return name.split(".").filter(Boolean).length === 2;
+}
+
+export const domainRoutingCheck: PostSynthCheck = {
+  id: "CPL030",
+  description: "Domain DNS mode, certificate challenge, and routing target must be a valid combination",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    // Workload types, so a `workloadLink` route can be checked for the stateful
+    // requirement that replica-direct routing carries.
+    const workloadTypes = new Map<string, string>();
+    for (const [entityName, entity] of entitiesOfType(ctx.entities, WORKLOAD)) {
+      workloadTypes.set(readString(entity, "name") ?? entityName, readString(entity, "spec", "type") ?? "serverless");
+    }
+
+    for (const [entityName, entity] of entitiesOfType(ctx.entities, DOMAIN)) {
+      const name = readString(entity, "name") ?? entityName;
+      const dnsMode = readString(entity, "spec", "dnsMode") ?? "cname";
+      const challenge = readString(entity, "spec", "certChallengeType");
+      const gvcLink = readString(entity, "spec", "gvcLink");
+      const workloadLink = readString(entity, "spec", "workloadLink");
+      const ports = readArray(entity, "spec", "ports");
+      const routed = ports.some((port) => readArray(port, "routes").length > 0);
+
+      if (dnsMode === "ns" && isApex(name)) {
+        diagnostics.push({
+          checkId: "CPL030",
+          severity: "error",
+          message:
+            `Domain "${name}" is an apex domain with dnsMode "ns". NS mode does not support apex domains — ` +
+            `use "cname".`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+      }
+
+      if (dnsMode === "ns" && challenge === "http01") {
+        diagnostics.push({
+          checkId: "CPL030",
+          severity: "error",
+          message:
+            `Domain "${name}" uses dnsMode "ns" with certChallengeType "http01", which is rejected. ` +
+            `NS mode requires "dns01".`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+      }
+
+      const targets = [gvcLink && "gvcLink", workloadLink && "workloadLink", routed && "ports[].routes"].filter(
+        Boolean,
+      ) as string[];
+
+      if (targets.length > 1) {
+        diagnostics.push({
+          checkId: "CPL030",
+          severity: "error",
+          message:
+            `Domain "${name}" sets ${targets.join(" and ")}. These are mutually exclusive ways of saying ` +
+            `where traffic goes — keep exactly one.`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+      }
+
+      if (targets.length === 0) {
+        diagnostics.push({
+          checkId: "CPL030",
+          severity: "warning",
+          message:
+            `Domain "${name}" names no routing target. Set one of gvcLink, workloadLink, or ports[].routes, ` +
+            `or the domain resolves to nothing.`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+      }
+
+      // `workloadLink` is replica-direct routing, which only stateful supports.
+      if (workloadLink) {
+        const link = parseLink(workloadLink);
+        const type = link && workloadTypes.get(link.name);
+        if (type && type !== "stateful") {
+          diagnostics.push({
+            checkId: "CPL030",
+            severity: "error",
+            message:
+              `Domain "${name}" routes via workloadLink to "${link!.name}", which is type "${type}". ` +
+              `workloadLink is replica-direct routing and is supported on stateful workloads only.`,
+            entity: entityName,
+            lexicon: "cpln",
+          });
+        }
+      }
+
+      // Every route in a domain must target workloads in one GVC.
+      const routeGvcs = new Set<string>();
+      for (const port of ports) {
+        for (const route of readArray(port, "routes")) {
+          const target = readString(route, "workloadLink");
+          const link = target ? parseLink(target) : undefined;
+          if (link?.gvc) routeGvcs.add(link.gvc);
+        }
+      }
+
+      if (routeGvcs.size > 1) {
+        diagnostics.push({
+          checkId: "CPL030",
+          severity: "error",
+          message:
+            `Domain "${name}" routes to workloads in ${routeGvcs.size} GVCs (${[...routeGvcs].sort().join(", ")}). ` +
+            `All routes in a domain must target workloads in the same GVC.`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+      }
+
+      if (readPath(entity, "spec", "acceptAllHosts") === true && readPath(entity, "spec", "acceptAllSubdomains") === true) {
+        diagnostics.push({
+          checkId: "CPL030",
+          severity: "error",
+          message: `Domain "${name}" sets both acceptAllHosts and acceptAllSubdomains; they are mutually exclusive.`,
+          entity: entityName,
+          lexicon: "cpln",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/cpl040-pinned-image.ts

@@ -0,0 +1,48 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readString } from "../../entity-props";
+import { WORKLOAD, entitiesOfType, imageTag } from "./helpers";
+
+/** A digest pin — `@sha256:…` — is reproducible regardless of tag. */
+const DIGEST = /@sha\d+:[0-9a-f]+$/i;
+
+/**
+ * CPL040: an image reference that is not pinned.
+ *
+ * `:latest`, or no tag at all (which *means* `:latest`), makes what runs a
+ * function of when the workload last happened to pull. On a serverless
+ * workload that scales to zero and cold-starts, that can be several times a
+ * day, so two replicas of "the same" deploy can be different builds.
+ */
+export const pinnedImageCheck: PostSynthCheck = {
+  id: "CPL040",
+  description: "Container images should be pinned to a specific tag or digest",
+
+  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") ?? "?";
+        const image = readString(container, "image");
+        if (!image || DIGEST.test(image)) continue;
+
+        const tag = imageTag(image);
+        if (tag && tag !== "latest") continue;
+
+        diagnostics.push({
+          checkId: "CPL040",
+          severity: "warning",
+          message:
+            `Workload "${name}" container "${containerName}" uses image "${image}", which is ` +
+            (tag === "latest" ? `tagged \`latest\`` : `untagged (implicitly \`latest\`)`) +
+            `. Pin a version or a digest — a scale-from-zero cold start re-pulls, so what runs can change ` +
+            `without a deploy.`,
+          entity: name,
+          lexicon: "cpln",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/cpl041-image-reference-form.ts

@@ -0,0 +1,60 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readArray, readString } from "../../entity-props";
+import { WORKLOAD, entitiesOfType } from "./helpers";
+
+/**
+ * CPL041: registry prefixes Control Plane does not want in a workload spec.
+ *
+ * Two documented traps. `docker.io/` must never be added to a public image —
+ * the exact string `nginx:latest` works and `docker.io/library/nginx:latest`
+ * does not. And `<org>.registry.cpln.io/…` is the hostname for `docker login`
+ * and `docker push` only; inside a workload spec the org's own images are
+ * addressed as `//image/NAME:TAG`.
+ */
+export const imageReferenceFormCheck: PostSynthCheck = {
+  id: "CPL041",
+  description: "Image references must not use docker.io/ or the registry hostname form",
+
+  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") ?? "?";
+        const image = readString(container, "image");
+        if (!image) continue;
+
+        if (image.startsWith("docker.io/")) {
+          const bare = image.replace(/^docker\.io\/(library\/)?/, "");
+          diagnostics.push({
+            checkId: "CPL041",
+            severity: "error",
+            message:
+              `Workload "${name}" container "${containerName}" uses image "${image}". Control Plane rejects ` +
+              `the docker.io/ prefix on public images — use "${bare}".`,
+            entity: name,
+            lexicon: "cpln",
+          });
+          continue;
+        }
+
+        const selfHosted = /^([a-z0-9-]+)\.registry\.cpln\.io\/(.+)$/.exec(image);
+        if (selfHosted) {
+          diagnostics.push({
+            checkId: "CPL041",
+            severity: "warning",
+            message:
+              `Workload "${name}" container "${containerName}" uses image "${image}". The ` +
+              `<org>.registry.cpln.io hostname is for \`docker login\` and \`docker push\`; in a workload ` +
+              `spec, an image in this org is "//image/${selfHosted[2]}". (A cross-org pull does use the ` +
+              `hostname form — ignore this if "${selfHosted[1]}" is another org.)`,
+            entity: name,
+            lexicon: "cpln",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};