@intentius/chant-lexicon-k8s 0.45.0 → 0.49.0

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

@@ -0,0 +1,76 @@
+/**
+ * Shared helper for the committed-encrypted secret checks: join each
+ * `declareSecret({ provenance: "committed-encrypted" })` in the entity map to
+ * the sidecar file the build emitted for it.
+ *
+ * The join has to go through `output.files`, not `getPrimaryOutput`. The
+ * ciphertext is deliberately kept OUT of the primary output — that is what
+ * makes applying an undecrypted Secret structurally impossible — so a check
+ * that reads only the primary output sees nothing at all here.
+ *
+ * Excluded from check auto-discovery by the "helper" filename filter.
+ */
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import type { CommittedEncryptedSecretDeclaration } from "@intentius/chant/secret-provenance";
+import { getAdditionalFiles } from "./k8s-helpers";
+import { committedEncryptedDeclarations, sidecarFilename, validateEncryptedSecretDocument, type EncryptedSecretDocument } from "../../sops/encrypted-secret-file";
+
+/** One committed-encrypted declaration, joined to what the build emitted for it. */
+export interface ResolvedEncryptedSecret {
+  /** The entity-map key the declaration was discovered under. */
+  entityName: string;
+  declaration: CommittedEncryptedSecretDeclaration;
+  /** The sidecar filename the declaration's path maps to. */
+  filename: string;
+  /** Undefined when the build emitted no such sidecar — the file did not resolve. */
+  text?: string;
+  /** Everything wrong with the emitted document. Empty when it is clean. */
+  problems: string[];
+  /** Parsed structure, when the document parsed at all. */
+  document?: EncryptedSecretDocument;
+}
+
+/** Every sidecar file across every lexicon output, keyed by filename. */
+export function allAdditionalFiles(ctx: PostSynthContext): Map<string, string> {
+  const files = new Map<string, string>();
+  for (const [, output] of ctx.outputs) {
+    for (const [filename, content] of Object.entries(getAdditionalFiles(output))) {
+      files.set(filename, content);
+    }
+  }
+  return files;
+}
+
+/**
+ * Join every committed-encrypted declaration to its emitted sidecar,
+ * validating the document as it goes. A declaration with no sidecar comes
+ * back with `text` undefined and one problem naming the missing file.
+ */
+export function resolveEncryptedSecretClaims(ctx: PostSynthContext): ResolvedEncryptedSecret[] {
+  const declarations = committedEncryptedDeclarations(ctx.entities);
+  if (declarations.size === 0) return [];
+
+  const files = allAdditionalFiles(ctx);
+  const resolved: ResolvedEncryptedSecret[] = [];
+
+  for (const [entityName, declaration] of declarations) {
+    const filename = sidecarFilename(declaration.file);
+    const text = files.get(filename);
+    if (text === undefined) {
+      resolved.push({
+        entityName,
+        declaration,
+        filename,
+        problems: [
+          `the build emitted no file for "${declaration.file}" — ` +
+            `the declared ciphertext did not resolve`,
+        ],
+      });
+      continue;
+    }
+    const { problems, document } = validateEncryptedSecretDocument(text, declaration);
+    resolved.push({ entityName, declaration, filename, text, problems, document });
+  }
+
+  return resolved;
+}

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

@@ -0,0 +1,55 @@
+/**
+ * WK8404: GPU request without a matching toleration
+ *
+ * A pod that requests `nvidia.com/gpu` but carries no toleration for the
+ * `nvidia.com/gpu` taint won't schedule onto a tainted GPU node pool (see
+ * `GpuNodePool`, #987, which taints its nodes `nvidia.com/gpu=present` by
+ * default). The pod sits `Pending` with `0/N nodes are available` until a
+ * toleration is added.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import {
+  getPrimaryOutput,
+  parseK8sManifests,
+  extractContainers,
+  extractPodSpec,
+  requestsGpu,
+  toleratesGpu,
+  GPU_POD_KINDS,
+} from "./k8s-helpers";
+
+export const wk8404: PostSynthCheck = {
+  id: "WK8404",
+  description: "GPU request without a matching nvidia.com/gpu toleration",
+
+  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);
+        if (!requestsGpu(containers)) 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",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,88 @@
+/**
+ * WK8405: Serving workload without a PodDisruptionBudget
+ *
+ * An InferenceService (or a Deployment carrying a serving
+ * `app.kubernetes.io/component` label — e.g. `inference-service` or
+ * `vllm-serving-runtime`) with no PodDisruptionBudget selecting it can lose
+ * every replica at once during a voluntary disruption (node drain, cluster
+ * upgrade), taking the model endpoint down. Serving workloads should ship
+ * with a PDB.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests } from "./k8s-helpers";
+import type { K8sManifest } from "./k8s-helpers";
+
+/** `app.kubernetes.io/component` values this lexicon's composites use for serving workloads. */
+const SERVING_COMPONENTS = new Set(["inference-service", "vllm-serving-runtime", "model-serving"]);
+
+function isServingWorkload(manifest: K8sManifest): boolean {
+  if (manifest.kind === "InferenceService") return true;
+  if (manifest.kind !== "Deployment" && manifest.kind !== "StatefulSet") return false;
+  const component = manifest.metadata?.labels?.["app.kubernetes.io/component"];
+  return component !== undefined && SERVING_COMPONENTS.has(component);
+}
+
+export const wk8405: PostSynthCheck = {
+  id: "WK8405",
+  description: "Serving workload (InferenceService / serving Deployment) has no PodDisruptionBudget",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      const pdbSelectors = collectPdbSelectors(manifests);
+
+      for (const manifest of manifests) {
+        if (!isServingWorkload(manifest)) continue;
+
+        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",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};
+
+function collectPdbSelectors(manifests: K8sManifest[]): Array<Record<string, string>> {
+  const selectors: Array<Record<string, string>> = [];
+
+  for (const manifest of manifests) {
+    if (manifest.kind !== "PodDisruptionBudget") continue;
+
+    const spec = manifest.spec;
+    if (!spec) continue;
+
+    const selector = spec.selector as Record<string, unknown> | undefined;
+    const matchLabels = selector?.matchLabels as Record<string, string> | undefined;
+
+    if (matchLabels && typeof matchLabels === "object") {
+      selectors.push(matchLabels);
+    }
+  }
+
+  return selectors;
+}
+
+function hasCoveringPdb(
+  workloadLabels: Record<string, string>,
+  pdbSelectors: Array<Record<string, string>>,
+): boolean {
+  return pdbSelectors.some((pdbLabels) =>
+    Object.entries(pdbLabels).every(([key, value]) => workloadLabels[key] === value),
+  );
+}

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

@@ -0,0 +1,60 @@
+/**
+ * WK8406: No resource limits on a GPU pod
+ *
+ * A container that requests `nvidia.com/gpu` but sets no cpu/memory limits
+ * can starve other pods on the same (expensive, scarce) GPU node of CPU and
+ * memory headroom. Unlike WK8201's general resource-limits guidance, this
+ * check is scoped to GPU-requesting containers specifically, since GPU node
+ * capacity is costlier and more contended than a general-purpose pool.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, extractContainers, GPU_POD_KINDS, NVIDIA_GPU_RESOURCE } from "./k8s-helpers";
+
+export const wk8406: PostSynthCheck = {
+  id: "WK8406",
+  description: "GPU-requesting container has no cpu/memory resource limits",
+
+  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",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,71 @@
+/**
+ * WK8407: Unpinned model version
+ *
+ * KServe's InferenceService predictor pins a model by `storageUri`. The
+ * `Model` composite (#986) always appends `version` as the trailing path
+ * segment (`scheme://id/version`), so a resolved `Model` reference is
+ * always pinned — but `InferenceService.model` also accepts a raw
+ * `storageUri` string (#985), which can bypass that guarantee (e.g.
+ * `"gs://bucket/model"` with no version segment, or a floating tag like
+ * `"latest"`/`"main"`). An unpinned reference means a redeploy of the same
+ * InferenceService can silently pick up different weights.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests } from "./k8s-helpers";
+
+/** Trailing path segments that mean "no explicit version" even though present. */
+const FLOATING_TAGS = new Set(["latest", "main", "master", "head"]);
+
+/**
+ * True when `storageUri` has an explicit, non-floating version segment:
+ * `scheme://path/version` with at least two path segments after the
+ * scheme, and the last segment isn't a known floating tag.
+ */
+export function isPinnedStorageUri(storageUri: string): boolean {
+  const m = /^[a-z][a-z0-9+.-]*:\/\/(.+)$/i.exec(storageUri.trim());
+  if (!m) return false;
+
+  const segments = m[1].split("/").filter((s) => s.length > 0);
+  if (segments.length < 2) return false;
+
+  const last = segments[segments.length - 1].toLowerCase();
+  return !FLOATING_TAGS.has(last);
+}
+
+export const wk8407: PostSynthCheck = {
+  id: "WK8407",
+  description: "InferenceService model storageUri has no explicit version segment",
+
+  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 !== "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;
+
+        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",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,220 @@
+/**
+ * WK8503: Workload consumes a Secret nothing in the output produces
+ *
+ * A pod that references a Secret which no manifest in the same build creates
+ * passes `chant build`, passes `chant lint`, applies cleanly — and then fails
+ * at pod start with `CreateContainerConfigError` (chant #1382). This check
+ * closes that gap with the same cross-resource bundle-join ARGO003 uses: every
+ * secret reference in a pod spec (envFrom.secretRef, env valueFrom
+ * secretKeyRef, secret volumes, projected secret sources, imagePullSecrets)
+ * must resolve to a Secret the output produces.
+ *
+ * Producers are the Secret manifests themselves plus the secret-materializing
+ * CRs the lexicon knows: `ExternalSecret` (spec.target.name, defaulting to the
+ * CR's own name), `InfisicalSecret` / `InfisicalDynamicSecret`
+ * (spec.managedSecretReference.secretName — its secretNamespace is honored
+ * separately from the CR's metadata.namespace), and cert-manager
+ * `Certificate` (spec.secretName). Namespaces must be compatible; a side with
+ * no namespace matches any.
+ *
+ * The typed waiver is a `SecretProvenance` declaration (chant #1828, epic
+ * #1365): a `declareSecret({ name, provenance: "referenced" | "from-provider"
+ * | "generated-once" })` covering the secret's name says the estate knows
+ * where the value comes from, and silences the check. That is what lets this
+ * ship at error severity with no suppression comment — a secret minted out of
+ * band is declared, not ignored. References marked `optional: true` are
+ * skipped (the author already said it may not exist).
+ *
+ * `committed-encrypted` is deliberately NOT in that waiver set. The other
+ * three kinds are promises about something outside the build; a
+ * committed-encrypted declaration is a claim about an artifact inside it, and
+ * the build emits that artifact. So it joins the PRODUCER set instead, with
+ * its namespace read from the emitted ciphertext (SOPS leaves metadata
+ * cleartext) — which means namespace matching applies to it exactly as it
+ * does to a literal Secret, and a declaration whose file is broken fails
+ * WK8504 rather than silently waiving this check.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { collectSecretDeclarations } from "@intentius/chant/secret-provenance";
+import { extractPodSpec, type K8sManifest } from "./k8s-helpers";
+import { allManifests } from "./argo-helpers";
+import { resolveEncryptedSecretClaims } from "./sops-helpers";
+
+/** A Secret some manifest in the output materializes. */
+interface ProducedSecret {
+  name: string;
+  namespace?: string;
+}
+
+/** One secret reference found in a pod spec. */
+interface SecretRef {
+  name: string;
+  /** Which field referenced it, for the message (e.g. "envFrom.secretRef"). */
+  via: string;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined;
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+/** Collect every Secret the output produces, from literal Secrets and the
+ * secret-materializing CR kinds the lexicon ships. */
+function collectProducedSecrets(manifests: K8sManifest[]): ProducedSecret[] {
+  const produced: ProducedSecret[] = [];
+  for (const m of manifests) {
+    const metaName = m.metadata?.name;
+    const metaNs = m.metadata?.namespace;
+    switch (m.kind) {
+      case "Secret": {
+        if (typeof metaName === "string") produced.push({ name: metaName, namespace: metaNs });
+        break;
+      }
+      case "ExternalSecret": {
+        // external-secrets.io — writes spec.target.name, defaulting to the CR's own name.
+        const target = asRecord(m.spec?.target);
+        const targetName = typeof target?.name === "string" ? target.name : metaName;
+        if (typeof targetName === "string") produced.push({ name: targetName, namespace: metaNs });
+        break;
+      }
+      case "InfisicalSecret":
+      case "InfisicalDynamicSecret": {
+        // secrets.infisical.com — writes spec.managedSecretReference.secretName;
+        // secretNamespace is carried separately from the CR's own namespace.
+        const ref = asRecord(m.spec?.managedSecretReference);
+        if (typeof ref?.secretName === "string") {
+          const ns = typeof ref.secretNamespace === "string" ? ref.secretNamespace : metaNs;
+          produced.push({ name: ref.secretName, namespace: ns });
+        }
+        break;
+      }
+      case "Certificate": {
+        // cert-manager — materializes the keypair into spec.secretName.
+        const secretName = m.spec?.secretName;
+        if (typeof secretName === "string") produced.push({ name: secretName, namespace: metaNs });
+        break;
+      }
+    }
+  }
+  return produced;
+}
+
+/** Collect every non-optional secret reference in a pod spec. */
+function collectSecretRefs(podSpec: Record<string, unknown>): SecretRef[] {
+  const refs: SecretRef[] = [];
+
+  const containers = [
+    ...asArray(podSpec.containers),
+    ...asArray(podSpec.initContainers),
+    ...asArray(podSpec.ephemeralContainers),
+  ];
+  for (const c of containers) {
+    const container = asRecord(c);
+    if (!container) continue;
+    for (const e of asArray(container.envFrom)) {
+      const secretRef = asRecord(asRecord(e)?.secretRef);
+      if (typeof secretRef?.name === "string" && secretRef.optional !== true) {
+        refs.push({ name: secretRef.name, via: "envFrom.secretRef" });
+      }
+    }
+    for (const e of asArray(container.env)) {
+      const keyRef = asRecord(asRecord(asRecord(e)?.valueFrom)?.secretKeyRef);
+      if (typeof keyRef?.name === "string" && keyRef.optional !== true) {
+        refs.push({ name: keyRef.name, via: "env[].valueFrom.secretKeyRef" });
+      }
+    }
+  }
+
+  for (const v of asArray(podSpec.volumes)) {
+    const volume = asRecord(v);
+    if (!volume) continue;
+    const secret = asRecord(volume.secret);
+    if (typeof secret?.secretName === "string" && secret.optional !== true) {
+      refs.push({ name: secret.secretName, via: "volumes[].secret.secretName" });
+    }
+    const projected = asRecord(volume.projected);
+    for (const s of asArray(projected?.sources)) {
+      const source = asRecord(asRecord(s)?.secret);
+      if (typeof source?.name === "string" && source.optional !== true) {
+        refs.push({ name: source.name, via: "volumes[].projected.sources[].secret" });
+      }
+    }
+  }
+
+  for (const p of asArray(podSpec.imagePullSecrets)) {
+    const pull = asRecord(p);
+    if (typeof pull?.name === "string") {
+      refs.push({ name: pull.name, via: "imagePullSecrets" });
+    }
+  }
+
+  return refs;
+}
+
+/** True when a produced Secret satisfies a reference. A side with no
+ * namespace matches any — only two explicit, different namespaces miss. */
+function producerCovers(producer: ProducedSecret, name: string, namespace: string | undefined): boolean {
+  if (producer.name !== name) return false;
+  return producer.namespace === undefined || namespace === undefined || producer.namespace === namespace;
+}
+
+export const wk8503: PostSynthCheck = {
+  id: "WK8503",
+  description:
+    "Workload consumes a Secret nothing in the output produces — produce it (Secret, ExternalSecret, InfisicalSecret, Certificate) or declare its provenance with declareSecret()",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const manifests = allManifests(ctx);
+    const produced = collectProducedSecrets(manifests);
+
+    // Committed ciphertext produces a Secret as surely as a Secret manifest
+    // does — Flux decrypts the emitted sidecar straight into the cluster — so
+    // it joins the producer set, namespace and all. A claim whose file did
+    // not resolve produces nothing: WK8504 reports why, and this check still
+    // fires, which is the point of not treating it as a waiver.
+    for (const claim of resolveEncryptedSecretClaims(ctx)) {
+      if (claim.problems.length > 0) continue;
+      produced.push({ name: claim.declaration.name, namespace: claim.document?.namespace });
+    }
+
+    // The typed waiver: a SecretProvenance declaration covering the name, for
+    // the three kinds whose value genuinely comes from outside this build.
+    const declaredNames = new Set<string>();
+    for (const decl of collectSecretDeclarations(ctx.entities).values()) {
+      if (decl.provenance === "committed-encrypted") continue;
+      declaredNames.add(decl.name);
+    }
+
+    for (const manifest of manifests) {
+      const podSpec = extractPodSpec(manifest);
+      if (!podSpec) continue;
+      const workload = manifest.metadata?.name ?? manifest.kind ?? "workload";
+      const namespace = manifest.metadata?.namespace;
+
+      const reported = new Set<string>();
+      for (const ref of collectSecretRefs(podSpec)) {
+        if (reported.has(ref.name)) continue;
+        if (declaredNames.has(ref.name)) continue;
+        if (produced.some((p) => producerCovers(p, ref.name, namespace))) continue;
+        reported.add(ref.name);
+        diagnostics.push({
+          checkId: "WK8503",
+          severity: "error",
+          message:
+            `${manifest.kind} "${workload}" consumes Secret "${ref.name}" (via ${ref.via}), ` +
+            `but nothing in the build output produces it — the pod will fail at start. ` +
+            `Produce it in this build, or declare its provenance: ` +
+            `declareSecret({ name: "${ref.name}", provenance: "referenced" }).`,
+          entity: workload,
+          lexicon: "k8s",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,51 @@
+/**
+ * WK8504: committed-encrypted secret declaration does not resolve
+ *
+ * `declareSecret({ provenance: "committed-encrypted", file })` is a claim
+ * about an artifact INSIDE the build, which is what separates it from the
+ * three kinds that promise something outside one. A claim inside the build
+ * should be verified rather than taken on trust, and this is the check that
+ * makes it falsifiable: it fires when the declared file produced no sidecar,
+ * when the emitted document is not a `v1` Secret of the declared name, when
+ * it carries no `sops` block, or when a `data`/`stringData` value is not
+ * `ENC[...]`-shaped.
+ *
+ * That last case is the failure this rule exists for: someone edits
+ * `db-credentials.sops.yaml` by hand, forgets `sops -e`, and commits
+ * plaintext. Before this, nothing in chant would notice.
+ *
+ * It reads `output.files`, not `getPrimaryOutput`. The ciphertext is
+ * deliberately kept out of the primary output — that is what makes applying
+ * an undecrypted Secret structurally impossible — so every other post-synth
+ * check in the lexicon is blind to it by construction, and this one has to
+ * ask for the sidecars explicitly.
+ *
+ * A value is only ever tested for the `ENC[` prefix; the message names the
+ * offending KEY, never what was found there.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { resolveEncryptedSecretClaims } from "./sops-helpers";
+
+export const wk8504: PostSynthCheck = {
+  id: "WK8504",
+  description:
+    "committed-encrypted secret declaration does not resolve — the declared file is missing, is not the named Secret, or is not encrypted",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const claim of resolveEncryptedSecretClaims(ctx)) {
+      for (const problem of claim.problems) {
+        diagnostics.push({
+          checkId: "WK8504",
+          severity: "error",
+          message: `declareSecret("${claim.declaration.name}"): ${problem}`,
+          entity: claim.declaration.name,
+          lexicon: "k8s",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};