@intentius/chant-lexicon-k8s 0.49.0 → 0.50.0

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

@@ -7,7 +7,7 @@
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
-import { getPrimaryOutput, parseK8sManifests, extractRayVersion } from "./k8s-helpers";
+import { docsToManifests, extractRayVersion } from "./k8s-helpers";
 
 export const wk8403: PostSynthCheck = {
   id: "WK8403",
@@ -16,42 +16,37 @@ export const wk8403: PostSynthCheck = {
   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 rayVersion = spec.rayVersion as string | undefined;
-        if (!rayVersion) continue; // WK8402 covers the missing case
-
-        // Extract version from head container image
-        const headGroupSpec = spec.headGroupSpec as Record<string, unknown> | undefined;
-        const tmpl = headGroupSpec?.template as Record<string, unknown> | undefined;
-        const podSpec = tmpl?.spec as Record<string, unknown> | undefined;
-        const containers = podSpec?.containers as Array<Record<string, unknown>> | undefined;
-        if (!Array.isArray(containers) || containers.length === 0) continue;
-
-        const image = containers[0].image as string | undefined;
-        if (!image) continue;
-
-        const imageVersion = extractRayVersion(image);
-        if (!imageVersion) continue; // Can't determine version from tag
-
-        if (imageVersion !== rayVersion) {
-          diagnostics.push({
-            checkId: "WK8403",
-            severity: "warning",
-            message: `RayCluster "${clusterName}": spec.rayVersion "${rayVersion}" does not match head image tag "${imageVersion}" — autoscaler may run a mismatched Ray version`,
-            entity: clusterName,
-            lexicon: "k8s",
-          });
-        }
+    for (const manifest of docsToManifests(ctx)) {
+      if (manifest.kind !== "RayCluster") continue;
+
+      const clusterName = manifest.metadata?.name ?? "RayCluster";
+      const spec = manifest.spec as Record<string, unknown> | undefined;
+      if (!spec) continue;
+
+      const rayVersion = spec.rayVersion as string | undefined;
+      if (!rayVersion) continue; // WK8402 covers the missing case
+
+      // Extract version from head container image
+      const headGroupSpec = spec.headGroupSpec as Record<string, unknown> | undefined;
+      const tmpl = headGroupSpec?.template as Record<string, unknown> | undefined;
+      const podSpec = tmpl?.spec as Record<string, unknown> | undefined;
+      const containers = podSpec?.containers as Array<Record<string, unknown>> | undefined;
+      if (!Array.isArray(containers) || containers.length === 0) continue;
+
+      const image = containers[0].image as string | undefined;
+      if (!image) continue;
+
+      const imageVersion = extractRayVersion(image);
+      if (!imageVersion) continue; // Can't determine version from tag
+
+      if (imageVersion !== rayVersion) {
+        diagnostics.push({
+          checkId: "WK8403",
+          severity: "warning",
+          message: `RayCluster "${clusterName}": spec.rayVersion "${rayVersion}" does not match head image tag "${imageVersion}" — autoscaler may run a mismatched Ray version`,
+          entity: clusterName,
+          lexicon: "k8s",
+        });
       }
     }
 

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

@@ -10,8 +10,7 @@
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
 import {
-  getPrimaryOutput,
-  parseK8sManifests,
+  docsToManifests,
   extractContainers,
   extractPodSpec,
   requestsGpu,
@@ -26,28 +25,23 @@ export const wk8404: PostSynthCheck = {
   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 docsToManifests(ctx)) {
+      if (!manifest.kind || !GPU_POD_KINDS.has(manifest.kind)) continue;
 
-      for (const manifest of manifests) {
-        if (!manifest.kind || !GPU_POD_KINDS.has(manifest.kind)) continue;
+      const containers = extractContainers(manifest);
+      if (!requestsGpu(containers)) continue;
 
-        const containers = extractContainers(manifest);
-        if (!requestsGpu(containers)) continue;
+      const podSpec = extractPodSpec(manifest);
+      if (toleratesGpu(podSpec?.tolerations)) continue;
 
-        const podSpec = extractPodSpec(manifest);
-        if (toleratesGpu(podSpec?.tolerations)) continue;
-
-        const resourceName = manifest.metadata?.name ?? manifest.kind;
-        diagnostics.push({
-          checkId: "WK8404",
-          severity: "error",
-          message: `${manifest.kind} "${resourceName}" requests nvidia.com/gpu but has no toleration for the nvidia.com/gpu taint — it will not schedule onto a tainted GPU node pool`,
-          entity: resourceName,
-          lexicon: "k8s",
-        });
-      }
+      const resourceName = manifest.metadata?.name ?? manifest.kind;
+      diagnostics.push({
+        checkId: "WK8404",
+        severity: "error",
+        message: `${manifest.kind} "${resourceName}" requests nvidia.com/gpu but has no toleration for the nvidia.com/gpu taint — it will not schedule onto a tainted GPU node pool`,
+        entity: resourceName,
+        lexicon: "k8s",
+      });
     }
 
     return diagnostics;

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

@@ -10,7 +10,7 @@
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
-import { getPrimaryOutput, parseK8sManifests } from "./k8s-helpers";
+import { docsToManifests } from "./k8s-helpers";
 import type { K8sManifest } from "./k8s-helpers";
 
 /** `app.kubernetes.io/component` values this lexicon's composites use for serving workloads. */
@@ -30,27 +30,24 @@ export const wk8405: PostSynthCheck = {
   check(ctx: PostSynthContext): PostSynthDiagnostic[] {
     const diagnostics: PostSynthDiagnostic[] = [];
 
-    for (const [, output] of ctx.outputs) {
-      const yaml = getPrimaryOutput(output);
-      const manifests = parseK8sManifests(yaml);
+    const manifests = docsToManifests(ctx);
 
-      const pdbSelectors = collectPdbSelectors(manifests);
+    const pdbSelectors = collectPdbSelectors(manifests);
 
-      for (const manifest of manifests) {
-        if (!isServingWorkload(manifest)) continue;
+    for (const manifest of manifests) {
+      if (!isServingWorkload(manifest)) continue;
 
-        const labels = manifest.metadata?.labels;
-        const resourceName = manifest.metadata?.name ?? manifest.kind ?? "workload";
+      const labels = manifest.metadata?.labels;
+      const resourceName = manifest.metadata?.name ?? manifest.kind ?? "workload";
 
-        if (!labels || !hasCoveringPdb(labels, pdbSelectors)) {
-          diagnostics.push({
-            checkId: "WK8405",
-            severity: "info",
-            message: `${manifest.kind} "${resourceName}" is a serving workload with no PodDisruptionBudget — add a PDB so a node drain or cluster upgrade cannot take down every replica at once`,
-            entity: resourceName,
-            lexicon: "k8s",
-          });
-        }
+      if (!labels || !hasCoveringPdb(labels, pdbSelectors)) {
+        diagnostics.push({
+          checkId: "WK8405",
+          severity: "info",
+          message: `${manifest.kind} "${resourceName}" is a serving workload with no PodDisruptionBudget — add a PDB so a node drain or cluster upgrade cannot take down every replica at once`,
+          entity: resourceName,
+          lexicon: "k8s",
+        });
       }
     }
 

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

@@ -9,7 +9,7 @@
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
-import { getPrimaryOutput, parseK8sManifests, extractContainers, GPU_POD_KINDS, NVIDIA_GPU_RESOURCE } from "./k8s-helpers";
+import { docsToManifests, extractContainers, GPU_POD_KINDS, NVIDIA_GPU_RESOURCE } from "./k8s-helpers";
 
 export const wk8406: PostSynthCheck = {
   id: "WK8406",
@@ -18,39 +18,34 @@ export const wk8406: PostSynthCheck = {
   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 || !GPU_POD_KINDS.has(manifest.kind)) continue;
-
-        const containers = extractContainers(manifest);
-        const resourceName = manifest.metadata?.name ?? manifest.kind;
-
-        for (const container of containers) {
-          const requests = container.resources?.requests as Record<string, unknown> | undefined;
-          const limits = container.resources?.limits as Record<string, unknown> | undefined;
-          const requestsGpu = Boolean(requests?.[NVIDIA_GPU_RESOURCE]) || Boolean(limits?.[NVIDIA_GPU_RESOURCE]);
-          if (!requestsGpu) continue;
-
-          const missing: string[] = [];
-          if (!limits || typeof limits !== "object") {
-            missing.push("cpu", "memory");
-          } else {
-            if (!limits.cpu) missing.push("cpu");
-            if (!limits.memory) missing.push("memory");
-          }
-
-          if (missing.length > 0) {
-            diagnostics.push({
-              checkId: "WK8406",
-              severity: "warning",
-              message: `GPU container "${container.name ?? "(unnamed)"}" in ${manifest.kind} "${resourceName}" is missing resource limits for ${missing.join(", ")} — a GPU pod without cpu/memory limits can starve its (scarce, expensive) node`,
-              entity: resourceName,
-              lexicon: "k8s",
-            });
-          }
+    for (const manifest of docsToManifests(ctx)) {
+      if (!manifest.kind || !GPU_POD_KINDS.has(manifest.kind)) continue;
+
+      const containers = extractContainers(manifest);
+      const resourceName = manifest.metadata?.name ?? manifest.kind;
+
+      for (const container of containers) {
+        const requests = container.resources?.requests as Record<string, unknown> | undefined;
+        const limits = container.resources?.limits as Record<string, unknown> | undefined;
+        const requestsGpu = Boolean(requests?.[NVIDIA_GPU_RESOURCE]) || Boolean(limits?.[NVIDIA_GPU_RESOURCE]);
+        if (!requestsGpu) continue;
+
+        const missing: string[] = [];
+        if (!limits || typeof limits !== "object") {
+          missing.push("cpu", "memory");
+        } else {
+          if (!limits.cpu) missing.push("cpu");
+          if (!limits.memory) missing.push("memory");
+        }
+
+        if (missing.length > 0) {
+          diagnostics.push({
+            checkId: "WK8406",
+            severity: "warning",
+            message: `GPU container "${container.name ?? "(unnamed)"}" in ${manifest.kind} "${resourceName}" is missing resource limits for ${missing.join(", ")} — a GPU pod without cpu/memory limits can starve its (scarce, expensive) node`,
+            entity: resourceName,
+            lexicon: "k8s",
+          });
         }
       }
     }

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

@@ -12,7 +12,7 @@
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
-import { getPrimaryOutput, parseK8sManifests } from "./k8s-helpers";
+import { docsToManifests } from "./k8s-helpers";
 
 /** Trailing path segments that mean "no explicit version" even though present. */
 const FLOATING_TAGS = new Set(["latest", "main", "master", "head"]);
@@ -40,29 +40,24 @@ export const wk8407: PostSynthCheck = {
   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 docsToManifests(ctx)) {
+      if (manifest.kind !== "InferenceService") continue;
 
-      for (const manifest of manifests) {
-        if (manifest.kind !== "InferenceService") continue;
+      const spec = manifest.spec as Record<string, unknown> | undefined;
+      const predictor = spec?.predictor as Record<string, unknown> | undefined;
+      const model = predictor?.model as Record<string, unknown> | undefined;
+      const storageUri = model?.storageUri as string | undefined;
+      if (!storageUri) continue;
 
-        const spec = manifest.spec as Record<string, unknown> | undefined;
-        const predictor = spec?.predictor as Record<string, unknown> | undefined;
-        const model = predictor?.model as Record<string, unknown> | undefined;
-        const storageUri = model?.storageUri as string | undefined;
-        if (!storageUri) continue;
-
-        if (!isPinnedStorageUri(storageUri)) {
-          const resourceName = manifest.metadata?.name ?? "InferenceService";
-          diagnostics.push({
-            checkId: "WK8407",
-            severity: "warning",
-            message: `InferenceService "${resourceName}": model storageUri "${storageUri}" has no explicit version segment — pin it (e.g. via the Model composite's required \`version\`) so a redeploy can't silently pick up different weights`,
-            entity: resourceName,
-            lexicon: "k8s",
-          });
-        }
+      if (!isPinnedStorageUri(storageUri)) {
+        const resourceName = manifest.metadata?.name ?? "InferenceService";
+        diagnostics.push({
+          checkId: "WK8407",
+          severity: "warning",
+          message: `InferenceService "${resourceName}": model storageUri "${storageUri}" has no explicit version segment — pin it (e.g. via the Model composite's required \`version\`) so a redeploy can't silently pick up different weights`,
+          entity: resourceName,
+          lexicon: "k8s",
+        });
       }
     }
 

package/src/op/builders.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Typed step-builder wrappers (chant #1288 Stage 2). Two things asserted:
+ *
+ *  - **Backward compat**: for every input core's original untyped builder
+ *    accepted, the new typed twin here produces a byte-identical
+ *    `ActivityStep` (own enumerable fields — `.out` is a non-enumerable
+ *    getter on both, per `builders.ts`'s `activity()`, so `toEqual` never
+ *    sees it). Same construction path (`activity()` + `takeProfileAndId`),
+ *    so this is really asserting the two call sites agree, not re-deriving
+ *    the logic.
+ *  - **Step-output refs compose**: a {@link StepOutputRef} in a typed slot
+ *    type-checks and lands in the step's `args` untouched (chant #1950).
+ *
+ * The `@ts-expect-error` block at the bottom is a compile-time-only check —
+ * never executed, just walked by `npm run typecheck` (tsc), which fails if a
+ * marked line does NOT error (an "unused '@ts-expect-error' directive").
+ */
+
+import { describe, test, expect } from "vitest";
+import {
+  kubectlApply as kubectlApplyOld,
+  waitForReady as waitForReadyOld,
+  ensureSecret as ensureSecretOld,
+  stepOutput,
+  type StepOutputRef,
+} from "@intentius/chant/op";
+import { kubectlApply, waitForReady, ensureSecret } from "./builders";
+
+describe("k8s typed step builders (#1288 Stage 2)", () => {
+  test("kubectlApply: identical ActivityStep to core's original for a minimal call", () => {
+    expect(kubectlApply("dist/k8s.yaml")).toEqual(kubectlApplyOld("dist/k8s.yaml"));
+  });
+
+  test("kubectlApply: identical ActivityStep with opts (profile override, force, deleteMode)", () => {
+    const opts = { context: "kind-dev", force: true, deleteMode: "owned-only" as const, profile: "fastIdempotent" as const };
+    expect(kubectlApply("dist/k8s.yaml", opts)).toEqual(kubectlApplyOld("dist/k8s.yaml", opts));
+  });
+
+  test("kubectlApply: accepts a StepOutputRef in a typed slot", () => {
+    const ref = stepOutput("build-step", "manifestPath");
+    const step = kubectlApply("dist/k8s.yaml", { context: ref });
+    expect(step.args?.context).toBe(ref);
+  });
+
+  test("waitForReady: identical ActivityStep to core's original", () => {
+    const opts = { namespace: "prod", intervalMs: 5000 };
+    expect(waitForReady("certificate", "my-cert", opts)).toEqual(waitForReadyOld("certificate", "my-cert", opts));
+  });
+
+  test("ensureSecret: identical ActivityStep to core's original", () => {
+    const opts = { metadata: { team: "platform" } };
+    expect(ensureSecret("db-creds", ["password"], opts)).toEqual(ensureSecretOld("db-creds", ["password"], opts));
+  });
+
+  test("kubectlApply: .out is reachable when an id is given", () => {
+    const step = kubectlApply("dist/k8s.yaml", { id: "apply" });
+    const ref: StepOutputRef = step.out.fieldManager;
+    expect(ref.step).toBe("apply");
+    expect(ref.path).toBe("fieldManager");
+  });
+});
+
+// ── Compile-time-only: authoring-time type errors (never executed) ──────────
+function _typeChecksOnly(): void {
+  // @ts-expect-error — "nameSpace" is not a key of KubectlApplyArgs (the
+  // exact typo class chant #1288 names: helmInstall("api", "./chart", {
+  // nameSpace: "prod" }) silently no-opped before this).
+  kubectlApply("dist/k8s.yaml", { nameSpace: "prod" });
+
+  // @ts-expect-error — deleteMode must be one of ApplyDeleteMode's literals.
+  kubectlApply("dist/k8s.yaml", { deleteMode: "always" });
+
+  // @ts-expect-error — force must be boolean, not a string.
+  kubectlApply("dist/k8s.yaml", { force: "yes" });
+
+  // @ts-expect-error — waitForReady's readiness spec field is misspelled.
+  waitForReady("certificate", "my-cert", { specc: {} });
+
+  // @ts-expect-error — ensureSecret's keys must be string[], not a single string.
+  ensureSecret("db-creds", "password");
+}
+void _typeChecksOnly;

package/src/op/builders.ts

@@ -0,0 +1,95 @@
+/**
+ * Typed step-builder wrappers for this lexicon's activities (chant #1288
+ * Stage 2 — "regenerate the step builders as fully typed wrappers"). Core
+ * cannot import a lexicon's `*Args` types (lexicons depend on core, not the
+ * other way around — see `packages/core/src/op/activity-contract.ts`'s module
+ * doc for the same layering constraint on Stage 1's contracts), so a fully
+ * typed `kubectlApply`/`waitForReady`/`ensureSecret` has to live beside the
+ * `*Args` interface it derives from: here, next to `./activities/kubectl.ts`
+ * etc. `opts`'s type in each wrapper below IS the activity's own `*Args`
+ * interface (via `Omit`/`WithStepRefs`) — never a hand-restated mirror — so
+ * `kubectlApply`/`waitForReady`/`ensureSecret`'s full option surface (the
+ * dozen-plus cross-field options on `kubectlApply` that Stage 1's zod
+ * contracts deliberately skipped rather than duplicate) is authoring-time
+ * typed for free, and stays in sync with the implementation by construction.
+ *
+ * Every field also accepts a {@link StepOutputRef} in its place
+ * ({@link WithStepRefs}, chant #1950) — a later step's args can consume an
+ * earlier step's declared output.
+ *
+ * `core`'s own `kubectlApply`/`waitForReady`/`ensureSecret` (in
+ * `@intentius/chant/op`, re-exported from `@intentius/chant-lexicon-temporal`
+ * for lexicon-agnostic single-import convenience) are UNCHANGED and produce
+ * byte-identical `ActivityStep` output for the same inputs — these are purely
+ * additive. Deliberately not swapped into the temporal barrel: that would
+ * make `@intentius/chant-lexicon-temporal` depend on this package (and on
+ * helm, for `helmInstall`) at runtime, which is exactly the "a worker image
+ * needs no kubectl binary" / "temporal stays product-agnostic" property the
+ * `op/activities/index.ts` module docs across this repo call out on purpose
+ * (activities were moved OUT of temporal into per-product lexicons for this
+ * reason; the step-builder layer shouldn't reintroduce the coupling from the
+ * other direction). An author who wants the typed surface imports it from
+ * here — `@intentius/chant-lexicon-k8s` — which a project using `kubectlApply`
+ * already depends on; existing `@intentius/chant-lexicon-temporal` imports
+ * keep working exactly as before, opting in only if the import is changed.
+ */
+
+import {
+  activity,
+  takeProfileAndId,
+  type ActivityStep,
+  type NamedActivityStep,
+  type WithStepRefs,
+} from "@intentius/chant/op";
+import type { KubectlApplyArgs } from "./activities/kubectl";
+import type { WaitForReadyArgs } from "./activities/wait-for-ready";
+import type { EnsureSecretActivityArgs } from "./activities/ensure-secret";
+
+/** Extra opts every wrapper below accepts alongside its activity's own fields. */
+type StepOpts = { profile?: ActivityStep["profile"]; id?: string };
+
+/**
+ * Run `kubectl apply -f <manifest>` — the fully typed twin of core's
+ * `kubectlApply` step-builder shortcut (chant #1288 Stage 2). `opts` is
+ * {@link KubectlApplyArgs} itself (minus the positional `manifest`) — every
+ * field `applyManifest` accepts, including `deleteMode`, `force`,
+ * `fieldManager`, `documents`, is authoring-time typed here, not just the
+ * subset a hand-written zod mirror would bother restating. Defaults to the
+ * `longInfra` profile (override via `opts.profile`).
+ */
+export const kubectlApply = (
+  manifest: string,
+  opts?: WithStepRefs<Omit<KubectlApplyArgs, "manifest">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("kubectlApply", { manifest, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+
+/**
+ * Poll a Kubernetes resource until it reports ready, driven by a data-only
+ * readiness spec (CRD-aware; #365) — the fully typed twin of core's
+ * `waitForReady`. `opts` is {@link WaitForReadyArgs} itself, minus the
+ * positional `kind`/`name`. Defaults to the `k8sWait` profile.
+ */
+export const waitForReady = (
+  kind: string,
+  name: string,
+  opts?: WithStepRefs<Omit<WaitForReadyArgs, "kind" | "name">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("waitForReady", { kind, name, ...args }, { profile: profile ?? "k8sWait", ...(id ? { id } : {}) });
+};
+
+/**
+ * Ensure a `generated-once` secret exists in the target store (#1829) — the
+ * fully typed twin of core's `ensureSecret`. `opts` is
+ * {@link EnsureSecretActivityArgs} itself, minus the positional `name`/`keys`.
+ */
+export const ensureSecret = (
+  name: string,
+  keys: string[],
+  opts?: WithStepRefs<Omit<EnsureSecretActivityArgs, "name" | "keys">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("ensureSecret", { name, keys, ...args }, { profile, ...(id ? { id } : {}) });
+};

package/src/serializer.ts

@@ -258,6 +258,8 @@ export const k8sSerializer: Serializer = {
     const otherDocs: string[] = [];
     /** Sidecar files — committed ciphertext, copied byte-for-byte. */
     const files: Record<string, string> = {};
+    /** Basenames within `files` that must never be JSON.parse round-tripped (chant#1937). */
+    const verbatimFiles: string[] = [];
     const warnings: string[] = [];
 
     for (const [name, entity] of entities) {
@@ -280,6 +282,7 @@ export const k8sSerializer: Serializer = {
           );
         }
         files[entity.filename] = entity.text;
+        if (!verbatimFiles.includes(entity.filename)) verbatimFiles.push(entity.filename);
         continue;
       }
 
@@ -417,7 +420,12 @@ export const k8sSerializer: Serializer = {
     // A bare string when there is nothing extra to write, so the common case
     // stays byte-identical to what every existing consumer already reads.
     if (Object.keys(files).length === 0 && warnings.length === 0) return primary;
-    return { primary, files, ...(warnings.length > 0 ? { warnings } : {}) };
+    return {
+      primary,
+      files,
+      ...(verbatimFiles.length > 0 ? { verbatimFiles } : {}),
+      ...(warnings.length > 0 ? { warnings } : {}),
+    };
   },
 };