@intentius/chant-lexicon-k8s 0.1.0 → 0.1.5

package/src/generated/index.d.ts

@@ -1244,6 +1244,36 @@ export declare class PVC {
   readonly uid: string;
 }
 
+export declare class RayCluster {
+  constructor(props: {
+    metadata?: Record<string, unknown>;
+    spec?: Record<string, unknown>;
+  });
+  readonly name: string;
+  readonly namespace: string;
+  readonly uid: string;
+}
+
+export declare class RayJob {
+  constructor(props: {
+    metadata?: Record<string, unknown>;
+    spec?: Record<string, unknown>;
+  });
+  readonly name: string;
+  readonly namespace: string;
+  readonly uid: string;
+}
+
+export declare class RayService {
+  constructor(props: {
+    metadata?: Record<string, unknown>;
+    spec?: Record<string, unknown>;
+  });
+  readonly name: string;
+  readonly namespace: string;
+  readonly uid: string;
+}
+
 export declare class ReplicaSet {
   constructor(props: {
     /** If the Labels of a ReplicaSet are empty, they are defaulted to be the same as the Pod(s) that the ReplicaSet manages. Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata */

package/src/generated/index.ts

@@ -96,6 +96,9 @@ export const PriorityLevelConfiguration = createResource("K8s::Flowcontrol::Prio
 export const PriorityLevelConfigurationList = createResource("K8s::Flowcontrol::PriorityLevelConfigurationList", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
 export const PV = createResource("K8s::Core::PersistentVolume", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
 export const PVC = createResource("K8s::Core::PersistentVolumeClaim", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
+export const RayCluster = createResource("K8s::Ray::RayCluster", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
+export const RayJob = createResource("K8s::Ray::RayJob", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
+export const RayService = createResource("K8s::Ray::RayService", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
 export const ReplicaSet = createResource("K8s::Apps::ReplicaSet", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
 export const ReplicaSetList = createResource("K8s::Apps::ReplicaSetList", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
 export const ReplicationController = createResource("K8s::Core::ReplicationController", "k8s", {"name":"name","namespace":"namespace","uid":"uid"});
@@ -186,6 +189,16 @@ export const PodSpec = createProperty("K8s::Core::PodSpec", "k8s");
 export const PodTemplateSpec = createProperty("K8s::Core::PodTemplateSpec", "k8s");
 export const PolicyRule = createProperty("K8s::Rbac::PolicyRule", "k8s");
 export const Probe = createProperty("K8s::Core::Probe", "k8s");
+export const RayCluster_AutoscalerOptions = createProperty("K8s::Ray::RayCluster.autoscalerOptions", "k8s");
+export const RayCluster_GcsFaultToleranceOptions = createProperty("K8s::Ray::RayCluster.gcsFaultToleranceOptions", "k8s");
+export const RayCluster_HeadGroupSpec = createProperty("K8s::Ray::RayCluster.headGroupSpec", "k8s");
+export const RayCluster_WorkerGroupSpec = createProperty("K8s::Ray::RayCluster.workerGroupSpecs", "k8s");
+export const RayJob_RayClusterSpec = createProperty("K8s::Ray::RayJob.rayClusterSpec", "k8s");
+export const RayJob_SubmitterConfig = createProperty("K8s::Ray::RayJob.submitterConfig", "k8s");
+export const RayJob_SubmitterPodTemplate = createProperty("K8s::Ray::RayJob.submitterPodTemplate", "k8s");
+export const RayService_RayClusterConfig = createProperty("K8s::Ray::RayService.rayClusterConfig", "k8s");
+export const RayService_ServeService = createProperty("K8s::Ray::RayService.serveService", "k8s");
+export const RayService_UpgradeStrategy = createProperty("K8s::Ray::RayService.upgradeStrategy", "k8s");
 export const ResourceRequirements = createProperty("K8s::Core::ResourceRequirements", "k8s");
 export const RoleRef = createProperty("K8s::Rbac::RoleRef", "k8s");
 export const RollingUpdateDeployment = createProperty("K8s::Apps::RollingUpdateDeployment", "k8s");

package/src/generated/lexicon-k8s.json

@@ -46,6 +46,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "AutoscalerOptions": {
+    "resourceType": "K8s::Ray::RayCluster.autoscalerOptions",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "BatchJob": {
     "resourceType": "K8s::Batch::Job",
     "kind": "resource",
@@ -439,6 +444,11 @@
     "apiVersion": "flowcontrol.apiserver.k8s.io/v1",
     "gvkKind": "FlowSchemaList"
   },
+  "GcsFaultToleranceOptions": {
+    "resourceType": "K8s::Ray::RayCluster.gcsFaultToleranceOptions",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "HPA": {
     "resourceType": "K8s::Autoscaling::HorizontalPodAutoscaler",
     "kind": "resource",
@@ -456,6 +466,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "HeadGroupSpec": {
+    "resourceType": "K8s::Ray::RayCluster.headGroupSpec",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "HorizontalPodAutoscaler": {
     "resourceType": "K8s::Autoscaling::HorizontalPodAutoscaler",
     "kind": "resource",
@@ -942,6 +957,87 @@
       }
     }
   },
+  "RayCluster": {
+    "resourceType": "K8s::Ray::RayCluster",
+    "kind": "resource",
+    "lexicon": "k8s",
+    "apiVersion": "ray.io/v1",
+    "gvkKind": "RayCluster"
+  },
+  "RayClusterConfig": {
+    "resourceType": "K8s::Ray::RayService.rayClusterConfig",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayClusterSpec": {
+    "resourceType": "K8s::Ray::RayJob.rayClusterSpec",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayCluster_AutoscalerOptions": {
+    "resourceType": "K8s::Ray::RayCluster.autoscalerOptions",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayCluster_GcsFaultToleranceOptions": {
+    "resourceType": "K8s::Ray::RayCluster.gcsFaultToleranceOptions",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayCluster_HeadGroupSpec": {
+    "resourceType": "K8s::Ray::RayCluster.headGroupSpec",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayCluster_WorkerGroupSpec": {
+    "resourceType": "K8s::Ray::RayCluster.workerGroupSpecs",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayJob": {
+    "resourceType": "K8s::Ray::RayJob",
+    "kind": "resource",
+    "lexicon": "k8s",
+    "apiVersion": "ray.io/v1",
+    "gvkKind": "RayJob"
+  },
+  "RayJob_RayClusterSpec": {
+    "resourceType": "K8s::Ray::RayJob.rayClusterSpec",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayJob_SubmitterConfig": {
+    "resourceType": "K8s::Ray::RayJob.submitterConfig",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayJob_SubmitterPodTemplate": {
+    "resourceType": "K8s::Ray::RayJob.submitterPodTemplate",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayService": {
+    "resourceType": "K8s::Ray::RayService",
+    "kind": "resource",
+    "lexicon": "k8s",
+    "apiVersion": "ray.io/v1",
+    "gvkKind": "RayService"
+  },
+  "RayService_RayClusterConfig": {
+    "resourceType": "K8s::Ray::RayService.rayClusterConfig",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayService_ServeService": {
+    "resourceType": "K8s::Ray::RayService.serveService",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayService_UpgradeStrategy": {
+    "resourceType": "K8s::Ray::RayService.upgradeStrategy",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "ReplicaSet": {
     "resourceType": "K8s::Apps::ReplicaSet",
     "kind": "resource",
@@ -1164,6 +1260,11 @@
     "apiVersion": "authorization.k8s.io/v1",
     "gvkKind": "SelfSubjectRulesReview"
   },
+  "ServeService": {
+    "resourceType": "K8s::Ray::RayService.serveService",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "Service": {
     "resourceType": "K8s::Core::Service",
     "kind": "resource",
@@ -1281,6 +1382,16 @@
     "apiVersion": "authorization.k8s.io/v1",
     "gvkKind": "SubjectAccessReview"
   },
+  "SubmitterConfig": {
+    "resourceType": "K8s::Ray::RayJob.submitterConfig",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "SubmitterPodTemplate": {
+    "resourceType": "K8s::Ray::RayJob.submitterPodTemplate",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "TCPSocketAction": {
     "resourceType": "K8s::Core::TCPSocketAction",
     "kind": "property",
@@ -1323,6 +1434,11 @@
       }
     }
   },
+  "UpgradeStrategy": {
+    "resourceType": "K8s::Ray::RayService.upgradeStrategy",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "ValidatingAdmissionPolicy": {
     "resourceType": "K8s::Admissionregistration::ValidatingAdmissionPolicy",
     "kind": "resource",
@@ -1409,5 +1525,10 @@
     "lexicon": "k8s",
     "apiVersion": "v1",
     "gvkKind": "WatchEvent"
+  },
+  "WorkerGroupSpec": {
+    "resourceType": "K8s::Ray::RayCluster.workerGroupSpecs",
+    "kind": "property",
+    "lexicon": "k8s"
   }
 }

package/src/import/generator.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "bun:test";
+import { describe, test, expect } from "vitest";
 import { K8sGenerator } from "./generator";
 import type { TemplateIR, ResourceIR } from "@intentius/chant/import/parser";
 

package/src/import/parser.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "bun:test";
+import { describe, test, expect } from "vitest";
 import { K8sParser } from "./parser";
 
 const parser = new K8sParser();

package/src/import/roundtrip.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "bun:test";
+import { describe, test, expect } from "vitest";
 import { readFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";

package/src/index.ts

@@ -22,6 +22,7 @@ export {
   IrsaServiceAccount, AlbIngress, EbsStorageClass, EfsStorageClass, FluentBitAgent, ExternalDnsAgent, AdotCollector,
   MetricsServer, WorkloadIdentityServiceAccount, GcePdStorageClass, FilestoreStorageClass, GkeGateway, ConfigConnectorContext,
   GceIngress, CockroachDbCluster,
+  RayCluster, RayJob, RayService,
   AgicIngress, AzureDiskStorageClass, AzureFileStorageClass, AzureMonitorCollector,
   AksWorkloadIdentityServiceAccount,
   GkeFluentBitAgent, GkeOtelCollector, GkeExternalDnsAgent, AksExternalDnsAgent,
@@ -44,6 +45,9 @@ export type {
   GkeGatewayProps, GkeGatewayResult,
   ConfigConnectorContextProps, ConfigConnectorContextResult,
   GceIngressProps, GceIngressResult, CockroachDbClusterProps, CockroachDbClusterResult,
+  RayClusterProps, RayClusterResult, RayClusterSpec, ResourceSpec, HeadGroupSpec, WorkerGroupSpec,
+  RayJobProps, RayJobResult,
+  RayServiceProps, RayServiceResult,
   AgicIngressProps, AgicIngressResult,
   AzureDiskStorageClassProps, AzureDiskStorageClassResult,
   AzureFileStorageClassProps, AzureFileStorageClassResult,

package/src/lint/post-synth/k8s-helpers.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "bun:test";
+import { describe, test, expect } from "vitest";
 import {
   parseK8sManifests,
   extractContainers,

package/src/lint/post-synth/k8s-helpers.ts

@@ -147,3 +147,42 @@ export const WORKLOAD_KINDS = new Set([
   "Job",
   "CronJob",
 ]);
+
+/**
+ * Parse a Kubernetes memory string to bytes.
+ *
+ * Handles binary suffixes (Ki, Mi, Gi, Ti) and SI suffixes (K, M, G, T).
+ * Returns NaN for unrecognised strings — callers should skip checks on NaN.
+ *
+ * @example
+ * parseMemoryBytes("4Gi")  // 4294967296
+ * parseMemoryBytes("512Mi") // 536870912
+ * parseMemoryBytes("2048") // 2048
+ */
+export function parseMemoryBytes(s: string): number {
+  const m = /^([0-9]+(?:\.[0-9]+)?)(Ki|Mi|Gi|Ti|K|M|G|T)?$/.exec(s.trim());
+  if (!m) return NaN;
+  const n = parseFloat(m[1]);
+  const multipliers: Record<string, number> = {
+    Ki: 1024, Mi: 1024 ** 2, Gi: 1024 ** 3, Ti: 1024 ** 4,
+    K: 1000, M: 1000 ** 2, G: 1000 ** 3, T: 1000 ** 4,
+  };
+  return n * (multipliers[m[2] ?? ""] ?? 1);
+}
+
+/**
+ * Extract the Ray version from an image tag.
+ *
+ * Looks for a semver-style version prefix in the image tag:
+ *   "rayproject/ray:2.40.0"          → "2.40.0"
+ *   "rayproject/ray:2.40.0-py310"    → "2.40.0"
+ *   "us-docker.pkg.dev/.../ray:2.9.3-gpu" → "2.9.3"
+ *   "rayproject/ray:latest"          → undefined
+ *
+ * Returns undefined when no version can be found.
+ */
+export function extractRayVersion(image: string): string | undefined {
+  const tag = image.includes(":") ? image.split(":").pop()! : image;
+  const m = /^([0-9]+\.[0-9]+\.[0-9]+)/.exec(tag);
+  return m ? m[1] : undefined;
+}

package/src/lint/post-synth/post-synth.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "bun:test";
+import { describe, test, expect } from "vitest";
 import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
 
 // Import all checks
@@ -25,6 +25,9 @@ import { wk8303 } from "./wk8303";
 import { wk8304 } from "./wk8304";
 import { wk8305 } from "./wk8305";
 import { wk8306 } from "./wk8306";
+import { wk8401 } from "./wk8401";
+import { wk8402 } from "./wk8402";
+import { wk8403 } from "./wk8403";
 
 function makeCtx(yaml: string): PostSynthContext {
   return {
@@ -1328,3 +1331,148 @@ describe("WK8306: Container command starts with flag", () => {
     expect(diags.length).toBe(0);
   });
 });
+
+// ── WK8401: shmSize exceeds memory limit ────────────────────────────────────
+
+function makeRayCluster(overrides: {
+  shmSizeLimit?: string;
+  memoryLimit?: string;
+  workerShmSizeLimit?: string;
+  workerMemoryLimit?: string;
+  rayVersion?: string;
+  headImage?: string;
+}) {
+  const headImage = overrides.headImage ?? "rayproject/ray:2.40.0-py310-cpu";
+  return JSON.stringify({
+    apiVersion: "ray.io/v1alpha1",
+    kind: "RayCluster",
+    metadata: { name: "ray" },
+    spec: {
+      ...(overrides.rayVersion !== undefined && { rayVersion: overrides.rayVersion }),
+      headGroupSpec: {
+        template: {
+          spec: {
+            volumes: [{ name: "dshm", emptyDir: { medium: "Memory", ...(overrides.shmSizeLimit !== undefined && { sizeLimit: overrides.shmSizeLimit }) } }],
+            containers: [{ name: "ray-head", image: headImage, resources: { limits: { memory: overrides.memoryLimit ?? "8Gi" } } }],
+          },
+        },
+      },
+      workerGroupSpecs: [
+        {
+          groupName: "cpu",
+          template: {
+            spec: {
+              volumes: [{ name: "dshm", emptyDir: { medium: "Memory", ...(overrides.workerShmSizeLimit !== undefined && { sizeLimit: overrides.workerShmSizeLimit }) } }],
+              containers: [{ name: "ray-worker", image: headImage, resources: { limits: { memory: overrides.workerMemoryLimit ?? "4Gi" } } }],
+            },
+          },
+        },
+      ],
+    },
+  });
+}
+
+describe("WK8401: shmSize exceeds memory limit", () => {
+  test("passes when shmSize equals memory limit", () => {
+    const ctx = makeCtx(makeRayCluster({ shmSizeLimit: "8Gi", memoryLimit: "8Gi" }));
+    const diags = wk8401.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8401").length).toBe(0);
+  });
+
+  test("passes when shmSize is less than memory limit", () => {
+    const ctx = makeCtx(makeRayCluster({ shmSizeLimit: "2Gi", memoryLimit: "8Gi" }));
+    const diags = wk8401.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8401").length).toBe(0);
+  });
+
+  test("errors when head shmSize exceeds memory limit", () => {
+    const ctx = makeCtx(makeRayCluster({ shmSizeLimit: "16Gi", memoryLimit: "8Gi" }));
+    const diags = wk8401.check(ctx);
+    const errors = diags.filter((d) => d.checkId === "WK8401" && d.severity === "error");
+    expect(errors.length).toBeGreaterThanOrEqual(1);
+    expect(errors[0].message).toContain("head");
+    expect(errors[0].message).toContain("16Gi");
+  });
+
+  test("errors when worker shmSize exceeds memory limit", () => {
+    const ctx = makeCtx(makeRayCluster({ workerShmSizeLimit: "8Gi", workerMemoryLimit: "4Gi" }));
+    const diags = wk8401.check(ctx);
+    const errors = diags.filter((d) => d.checkId === "WK8401" && d.severity === "error");
+    expect(errors.length).toBeGreaterThanOrEqual(1);
+    expect(errors[0].message).toContain("worker");
+  });
+
+  test("skips check when no sizeLimit set on emptyDir", () => {
+    const ctx = makeCtx(makeRayCluster({ shmSizeLimit: undefined }));
+    const diags = wk8401.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8401").length).toBe(0);
+  });
+
+  test("ignores non-RayCluster manifests", () => {
+    const ctx = makeCtx(JSON.stringify({
+      apiVersion: "apps/v1",
+      kind: "Deployment",
+      metadata: { name: "app" },
+      spec: { template: { spec: { volumes: [{ name: "dshm", emptyDir: { medium: "Memory", sizeLimit: "16Gi" } }], containers: [{ name: "app", image: "app:1.0", resources: { limits: { memory: "4Gi" } } }] } } },
+    }));
+    const diags = wk8401.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8401").length).toBe(0);
+  });
+});
+
+// ── WK8402: RayCluster missing spec.rayVersion ───────────────────────────────
+
+describe("WK8402: RayCluster missing spec.rayVersion", () => {
+  test("passes when rayVersion is set", () => {
+    const ctx = makeCtx(makeRayCluster({ rayVersion: "2.40.0" }));
+    const diags = wk8402.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8402").length).toBe(0);
+  });
+
+  test("warns when rayVersion is absent", () => {
+    const ctx = makeCtx(makeRayCluster({}));
+    const diags = wk8402.check(ctx);
+    const warns = diags.filter((d) => d.checkId === "WK8402");
+    expect(warns.length).toBe(1);
+    expect(warns[0].severity).toBe("warning");
+    expect(warns[0].message).toContain("latest");
+  });
+
+  test("ignores non-RayCluster manifests", () => {
+    const ctx = makeCtx(JSON.stringify({ apiVersion: "apps/v1", kind: "Deployment", metadata: { name: "app" }, spec: {} }));
+    const diags = wk8402.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8402").length).toBe(0);
+  });
+});
+
+// ── WK8403: spec.rayVersion / image tag mismatch ─────────────────────────────
+
+describe("WK8403: spec.rayVersion does not match image tag", () => {
+  test("passes when versions match", () => {
+    const ctx = makeCtx(makeRayCluster({ rayVersion: "2.40.0", headImage: "rayproject/ray:2.40.0-py310-cpu" }));
+    const diags = wk8403.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8403").length).toBe(0);
+  });
+
+  test("warns when rayVersion does not match image tag", () => {
+    const ctx = makeCtx(makeRayCluster({ rayVersion: "2.39.0", headImage: "rayproject/ray:2.40.0-py310-cpu" }));
+    const diags = wk8403.check(ctx);
+    const warns = diags.filter((d) => d.checkId === "WK8403");
+    expect(warns.length).toBe(1);
+    expect(warns[0].severity).toBe("warning");
+    expect(warns[0].message).toContain("2.39.0");
+    expect(warns[0].message).toContain("2.40.0");
+  });
+
+  test("skips when rayVersion is absent (WK8402 covers that)", () => {
+    const ctx = makeCtx(makeRayCluster({ headImage: "rayproject/ray:2.40.0" }));
+    const diags = wk8403.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8403").length).toBe(0);
+  });
+
+  test("skips when image tag has no parseable version", () => {
+    const ctx = makeCtx(makeRayCluster({ rayVersion: "2.40.0", headImage: "rayproject/ray:latest" }));
+    const diags = wk8403.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8403").length).toBe(0);
+  });
+});

package/src/lint/post-synth/wk8401.ts

@@ -0,0 +1,98 @@
+/**
+ * WK8401: shmSize exceeds container memory limit
+ *
+ * A RayCluster pod uses an emptyDir volume with medium: Memory for /dev/shm.
+ * Kubernetes counts that memory against the container's memory limit — if the
+ * sizeLimit exceeds the container's memory limit the pod will never schedule
+ * (Kubelet rejects it with "Invalid value … must be less than or equal to memory limit").
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, parseMemoryBytes } from "./k8s-helpers";
+
+export const wk8401: PostSynthCheck = {
+  id: "WK8401",
+  description: "shmSize must not exceed the container memory limit — pod will not schedule if it does",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (manifest.kind !== "RayCluster") continue;
+
+        const clusterName = manifest.metadata?.name ?? "RayCluster";
+        const spec = manifest.spec as Record<string, unknown> | undefined;
+        if (!spec) continue;
+
+        const groups: Array<{ label: string; templateSpec: Record<string, unknown> }> = [];
+
+        // Head group
+        const headGroupSpec = spec.headGroupSpec as Record<string, unknown> | undefined;
+        if (headGroupSpec) {
+          const tmpl = headGroupSpec.template as Record<string, unknown> | undefined;
+          const podSpec = tmpl?.spec as Record<string, unknown> | undefined;
+          if (podSpec) groups.push({ label: "head", templateSpec: podSpec });
+        }
+
+        // Worker groups
+        const workerGroupSpecs = spec.workerGroupSpecs as Array<Record<string, unknown>> | undefined;
+        if (Array.isArray(workerGroupSpecs)) {
+          for (const wg of workerGroupSpecs) {
+            const name = (wg.groupName as string | undefined) ?? "worker";
+            const tmpl = wg.template as Record<string, unknown> | undefined;
+            const podSpec = tmpl?.spec as Record<string, unknown> | undefined;
+            if (podSpec) groups.push({ label: `worker "${name}"`, templateSpec: podSpec });
+          }
+        }
+
+        for (const { label, templateSpec } of groups) {
+          // Find the emptyDir Memory volume (dshm)
+          const volumes = templateSpec.volumes as Array<Record<string, unknown>> | undefined;
+          if (!Array.isArray(volumes)) continue;
+
+          for (const vol of volumes) {
+            const emptyDir = vol.emptyDir as Record<string, unknown> | undefined;
+            if (!emptyDir || emptyDir.medium !== "Memory") continue;
+
+            const sizeLimit = emptyDir.sizeLimit as string | undefined;
+            if (!sizeLimit) continue;
+
+            const shmBytes = parseMemoryBytes(sizeLimit);
+            if (isNaN(shmBytes)) continue;
+
+            // Find memory limit from the first container that mounts this volume
+            const containers = templateSpec.containers as Array<Record<string, unknown>> | undefined;
+            if (!Array.isArray(containers)) continue;
+
+            for (const container of containers) {
+              const resources = container.resources as Record<string, unknown> | undefined;
+              const limits = resources?.limits as Record<string, unknown> | undefined;
+              const memLimit = limits?.memory as string | undefined;
+              if (!memLimit) continue;
+
+              const memBytes = parseMemoryBytes(memLimit);
+              if (isNaN(memBytes)) continue;
+
+              if (shmBytes > memBytes) {
+                diagnostics.push({
+                  checkId: "WK8401",
+                  severity: "error",
+                  message: `RayCluster "${clusterName}" ${label}: shmSize "${sizeLimit}" exceeds memory limit "${memLimit}" — pod will not schedule`,
+                  entity: clusterName,
+                  lexicon: "k8s",
+                });
+              }
+              break; // Only check the first container per group
+            }
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/wk8402.ts

@@ -0,0 +1,43 @@
+/**
+ * WK8402: RayCluster missing spec.rayVersion
+ *
+ * KubeRay uses spec.rayVersion to select the Ray autoscaler sidecar image.
+ * Without it, KubeRay defaults to the "latest" tag — autoscaler and Ray head
+ * may run mismatched versions, leading to silent protocol failures.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests } from "./k8s-helpers";
+
+export const wk8402: PostSynthCheck = {
+  id: "WK8402",
+  description: "RayCluster should set spec.rayVersion so KubeRay selects the correct autoscaler image",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (manifest.kind !== "RayCluster") continue;
+
+        const name = manifest.metadata?.name ?? "RayCluster";
+        const rayVersion = (manifest.spec as Record<string, unknown> | undefined)?.rayVersion;
+
+        if (!rayVersion) {
+          diagnostics.push({
+            checkId: "WK8402",
+            severity: "warning",
+            message: `RayCluster "${name}" is missing spec.rayVersion — KubeRay autoscaler will pull the "latest" image tag`,
+            entity: name,
+            lexicon: "k8s",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};