@intentius/chant-lexicon-helm 0.46.0 → 0.49.0

package/src/render.ts

@@ -44,6 +44,16 @@ import { Composite } from "@intentius/chant";
 import { Deployment } from "@intentius/chant-lexicon-k8s/generated/index";
 import yaml from "js-yaml";
 
+import { resolveCapabilityProfile, type HelmCapabilityProfile, type HelmCapabilityProfileRef } from "./config";
+import { helmContentDigest, helmInputDigest } from "./render-digest";
+import {
+  findRenderByCacheKey,
+  loadRenderContent,
+  persistHelmRender,
+  renderCacheKey,
+} from "./render-store";
+import { probeCoalescedValues, type CoalescedValuesProbe } from "./values-probe";
+
 export interface HelmRenderProps {
   /** Logical name for the render (used in cache key + composite name). */
   name: string;
@@ -64,6 +74,95 @@ export interface HelmRenderProps {
    * fresh render.
    */
   noCache?: boolean;
+  /**
+   * Capability profile the render is pinned against (#1235, epic #1228).
+   *
+   * A string names a profile declared in `chant.config.ts`'s
+   * `helm.capabilityProfiles` (per cluster — see `./config.ts`); an inline
+   * object carries the same facts directly. When set, `helm template` runs
+   * with `--kube-version` and `--api-versions` from the profile, so
+   * `.Capabilities` reflects the declared cluster instead of whatever the
+   * helm binary defaults to. A named profile the config does not declare is
+   * an error at synth, never a silent fallback. Absent, rendering is
+   * unpinned — exactly today's behavior.
+   */
+  capabilityProfile?: HelmCapabilityProfileRef;
+  /**
+   * Whether this render persists to the content-addressed render store
+   * (#1238) — canonical bytes under their `contentDigest` plus a
+   * `RenderManifest`, in `~/.chant/helm-renders/sha256-<hex>/` (see
+   * ./render-store.ts).
+   *
+   * Only a pinned render (capabilityProfile present) can persist — an
+   * unpinned render has no content identity, and `persist: true` on one is
+   * a synth error naming that reason. For pinned renders the default
+   * follows the cache knob: persistence is on unless `noCache` is set
+   * (`noCache: true` + `persist: true` forces a fresh render that is still
+   * persisted; `persist: false` turns the store off entirely).
+   */
+  persist?: boolean;
+  /**
+   * Source ref/commit to record in the persisted `RenderManifest`, when the
+   * caller has one. Never resolved implicitly and never fabricated — absent
+   * means the manifest records `sourceRef: null`.
+   */
+  sourceRef?: string;
+}
+
+/**
+ * What one `HelmRender` invocation recorded about itself. `capabilityProfile`
+ * is the profile identity the render was pinned against; `undefined` means
+ * the render was unpinned and its bytes depend on the local helm binary's
+ * defaults.
+ *
+ * Pinned renders (profile present — the v1 gate, see #1237) also carry the
+ * digest pair:
+ *
+ * - `inputDigest` — `sha256:` over the canonical JSON of the declared inputs
+ *   (chart reference, version, values, capability facts). Shared with the
+ *   release-ledger digest #1243 records on deploy, via `helmInputDigest`.
+ *   Answers "same inputs?" without touching any bytes.
+ * - `contentDigest` — `sha256:` over the canonical rendered bytes
+ *   (`canonicalizeRender`). The artifact identity: answers "same bytes on
+ *   the cluster?".
+ *
+ * They diverge exactly when the render is not a function of its declared
+ * inputs — `renderStability` in ./render-digest.ts names that.
+ *
+ * Unpinned renders record neither digest. Their bytes are a function of the
+ * local helm binary's defaulted capabilities, so a digest over them would
+ * assert an identity the render does not have — it would differ across
+ * machines that did nothing differently, and equal digests would still
+ * prove nothing about a cluster. No digest is the honest record.
+ */
+export interface HelmRenderRecord {
+  /** The render's logical name (`HelmRenderProps.name`) — also the helm release name baked into the bytes. */
+  name: string;
+  chart: string;
+  version?: string;
+  capabilityProfile?: HelmCapabilityProfile;
+  /** Input-side identity (#1237/#1243). Present only for pinned renders. */
+  inputDigest?: string;
+  /** Content-side identity over canonical rendered bytes (#1237). Present only for pinned renders. */
+  contentDigest?: string;
+  /**
+   * The build-time coalesced-values probe's digest (#1251), present only
+   * when the probe ran — a pinned render of a local chart (the probe needs
+   * the chart source on disk, so a repo-fetched chart never gets one).
+   */
+  coalescedValuesDigest?: string;
+}
+
+const renderRecords: HelmRenderRecord[] = [];
+
+/** Every render recorded in this process, in invocation order. */
+export function getHelmRenderRecords(): readonly HelmRenderRecord[] {
+  return renderRecords;
+}
+
+/** Reset the record list (test isolation). */
+export function clearHelmRenderRecords(): void {
+  renderRecords.length = 0;
 }
 
 interface RenderedDoc {
@@ -75,22 +174,61 @@ interface RenderedDoc {
 
 const CACHE_ROOT = join(homedir(), ".chant", "helm-renders");
 
-function cacheKey(props: HelmRenderProps): string {
+/**
+ * Legacy cache key — truncated, unprefixed, input-derived. Since #1238 this
+ * keys only *unpinned* renders (and names the values tempfile): pinned
+ * renders live in the content-addressed store (./render-store.ts) under
+ * their full `sha256:` contentDigest, with the inputs index providing cache
+ * hits. Existing truncated-hash entries stay where they are — a new root,
+ * not a migration.
+ */
+function cacheKey(props: HelmRenderProps, profile?: HelmCapabilityProfile): string {
   const stable = JSON.stringify({
     repo: props.repo,
     chart: props.chart,
     version: props.version,
     namespace: props.namespace ?? null,
     values: props.values ?? null,
+    // Only present for pinned renders (which no longer read this cache but
+    // still name their values tempfile with this key). A pinned render must
+    // never reuse an unpinned render's bytes (or another profile's) — the
+    // profile is a real render input (#1235).
+    ...(profile
+      ? {
+          capabilityProfile: {
+            name: profile.name,
+            kubeVersion: profile.kubeVersion,
+            apiVersions: profile.apiVersions ?? [],
+          },
+        }
+      : {}),
   });
   return createHash("sha256").update(stable).digest("hex").slice(0, 16);
 }
 
-function renderViaHelm(props: HelmRenderProps): string {
+/**
+ * Version of the local helm binary, for the persisted `RenderManifest`.
+ * Load-bearing there — the defaulted kube version is a property of the
+ * binary, so this field explains a digest mismatch between machines. Never
+ * fails a build: `"unknown"` when helm cannot answer.
+ */
+function helmBinaryVersion(): string {
+  try {
+    const out = execFileSync("helm", ["version", "--template", "{{.Version}}"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return out.trim().split("\n")[0] || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function renderViaHelm(props: HelmRenderProps, profile?: HelmCapabilityProfile): string {
   // Write values overrides to a tempfile if any.
   let valuesArgs: string[] = [];
   if (props.values && Object.keys(props.values).length > 0) {
-    const valuesPath = join(tmpdir(), `chant-helm-values-${cacheKey(props)}.yaml`);
+    const valuesPath = join(tmpdir(), `chant-helm-values-${cacheKey(props, profile)}.yaml`);
     writeFileSync(valuesPath, yaml.dump(props.values));
     valuesArgs = ["--values", valuesPath];
   }
@@ -124,6 +262,17 @@ function renderViaHelm(props: HelmRenderProps): string {
     // Without this, `helm template` silently drops manifests shipped in the
     // chart's (or a subchart's) crds/ directory.
     "--include-crds",
+    // Pin .Capabilities to the declared cluster profile. Without these, the
+    // kube version defaults to one baked into the helm binary and APIVersions
+    // is empty — both silently, both making the rendered bytes a function of
+    // the local toolchain (#1235).
+    ...(profile
+      ? [
+          "--kube-version",
+          profile.kubeVersion,
+          ...(profile.apiVersions ?? []).flatMap((v) => ["--api-versions", v]),
+        ]
+      : []),
     ...fetchArgs,
     ...isolationArgs,
     ...(props.namespace ? ["--namespace", props.namespace] : []),
@@ -149,16 +298,16 @@ function renderViaHelm(props: HelmRenderProps): string {
   }
 }
 
-function loadOrRender(props: HelmRenderProps): string {
+function loadOrRender(props: HelmRenderProps, profile?: HelmCapabilityProfile): string {
   if (props.noCache) {
-    return renderViaHelm(props);
+    return renderViaHelm(props, profile);
   }
-  const cacheDir = join(CACHE_ROOT, cacheKey(props));
+  const cacheDir = join(CACHE_ROOT, cacheKey(props, profile));
   const cachePath = join(cacheDir, "manifests.yaml");
   if (existsSync(cachePath)) {
     return readFileSync(cachePath, "utf8");
   }
-  const out = renderViaHelm(props);
+  const out = renderViaHelm(props, profile);
   try {
     mkdirSync(cacheDir, { recursive: true });
     writeFileSync(cachePath, out);
@@ -168,6 +317,112 @@ function loadOrRender(props: HelmRenderProps): string {
   return out;
 }
 
+/**
+ * Best-effort coalesced-values probe (#1251) for a `HelmRender` invocation.
+ *
+ * The probe (`./values-probe.ts`) needs the chart source on disk — the same
+ * requirement the pinnability classifier (#1234) has — so it only runs for
+ * a local chart (`props.repo` unset, `props.chart` a directory with a
+ * `Chart.yaml`). A repo-fetched chart's source is never kept on disk here,
+ * so it gets no probe, the same v1 gate `render.ts`'s digest recording
+ * already documents.
+ *
+ * Never fatal: a probe failure (a chart the probe's template injection
+ * can't render, `helm` briefly unavailable, ...) must not break the actual
+ * render it is only observing. `undefined` means "no probe result" — never
+ * fabricated, and WHM504 simply has nothing to report for this render.
+ */
+function runValuesProbeBestEffort(props: HelmRenderProps): CoalescedValuesProbe | undefined {
+  if (props.repo) return undefined;
+  if (!existsSync(join(props.chart, "Chart.yaml"))) return undefined;
+  try {
+    return probeCoalescedValues({
+      chartDir: props.chart,
+      name: props.name,
+      releaseName: props.name,
+      namespace: props.namespace,
+      supplied:
+        props.values && Object.keys(props.values).length > 0
+          ? [{ origin: "supplied file", values: props.values }]
+          : [],
+    });
+  } catch {
+    // Non-fatal — see the docstring above. The main render already ran (or
+    // is about to) via its own `helm template` invocation; this extra,
+    // probe-only render observing the same chart is never load-bearing.
+    return undefined;
+  }
+}
+
+/**
+ * The pinned render path (#1238): the content-addressed store is both the
+ * cache and the durable record.
+ *
+ * Read: unless `noCache` (or `persist: false`) is set, the full-inputs
+ * cache key resolves through the store's inputs index to canonical bytes a
+ * previous identical render stored — semantically identical to helm's
+ * output (canonicalization only normalizes render noise) and byte-stable
+ * under re-canonicalization, so digests recompute identically.
+ *
+ * Write: a fresh render persists { canonical bytes, RenderManifest } unless
+ * the caller opted out — the manifest is written alongside every pinned
+ * render by default. `persist: true` with `noCache` still persists (a
+ * forced-fresh render is still a durable artifact); a persist failure on
+ * the default path is non-fatal like a legacy cache-write failure, but an
+ * explicit `persist: true` surfaces it.
+ */
+function loadOrRenderPinned(
+  props: HelmRenderProps,
+  profile: HelmCapabilityProfile,
+  valuesProbe?: CoalescedValuesProbe,
+): string {
+  const chartRef = props.repo ? `${props.repo}/${props.chart}` : props.chart;
+  const storeRead = !props.noCache && props.persist !== false;
+  const storeWrite = props.persist === true || (!props.noCache && props.persist !== false);
+  const key = renderCacheKey({
+    chart: chartRef,
+    chartVersion: props.version,
+    releaseName: props.name,
+    namespace: props.namespace,
+    values: props.values,
+    capabilityProfile: profile,
+  });
+
+  if (storeRead) {
+    const hit = findRenderByCacheKey(key);
+    if (hit) {
+      const content = loadRenderContent(hit.contentDigest);
+      if (content !== undefined) return content;
+      // Index points at pruned/corrupt content — fall through and re-render.
+    }
+  }
+
+  const out = renderViaHelm(props, profile);
+  if (storeWrite) {
+    try {
+      persistHelmRender({
+        rendered: out,
+        releaseName: props.name,
+        chart: props.chart,
+        repo: props.repo || undefined,
+        chartVersion: props.version,
+        namespace: props.namespace,
+        values: props.values,
+        capabilityProfile: profile,
+        helmVersion: helmBinaryVersion(),
+        sourceRef: props.sourceRef,
+        coalescedValuesDigest: valuesProbe?.digest,
+        valueSources: valuesProbe?.valueSources,
+      });
+    } catch (err) {
+      if (props.persist === true) throw err;
+      // Default-on persistence degrades like a legacy cache-write failure:
+      // the render is still in memory and the build goes on.
+    }
+  }
+  return out;
+}
+
 function parseMultiDoc(text: string): RenderedDoc[] {
   const docs = yaml.loadAll(text);
   return docs
@@ -184,9 +439,65 @@ function safeKey(input: string): string {
 }
 
 export const HelmRender = Composite<HelmRenderProps>((props) => {
-  const yamlText = loadOrRender(props);
+  // Resolve first: a named profile the config does not declare must fail the
+  // build here, before any helm invocation could silently render against the
+  // binary's default capabilities.
+  const profile = props.capabilityProfile !== undefined ? resolveCapabilityProfile(props.capabilityProfile) : undefined;
+
+  if (!profile && props.persist === true) {
+    throw new Error(
+      `HelmRender "${props.name}": persist requires a pinned render, and this one is unpinned ` +
+        `(no capabilityProfile declared). An unpinned render's bytes are a function of the local ` +
+        `helm binary's defaulted capabilities, so they have no stable content identity to store ` +
+        `under. Declare capabilityProfile to pin the render (#1235), or drop persist.`,
+    );
+  }
+
+  // Build-time coalesced-values probe (#1251/#1252). Runs (best-effort) for
+  // a pinned render of a local chart — the same gate the digests below use,
+  // since the probe needs the chart source on disk and only a pinned render
+  // has a RenderManifest to carry its digest. `probeCoalescedValues` records
+  // itself into the WHM504 surface (`getValuesProbeRecords`) as part of
+  // running — no separate `recordValuesProbe` call needed here, and any
+  // dead assignment it found is worth reporting whether or not this render
+  // ultimately persists.
+  const valuesProbe = profile ? runValuesProbeBestEffort(props) : undefined;
+
+  const yamlText = profile ? loadOrRenderPinned(props, profile, valuesProbe) : loadOrRender(props, undefined);
   const docs = parseMultiDoc(yamlText);
 
+  // Digests are recorded only for pinned renders (#1237). Profile presence
+  // is the v1 gate: the classifier (#1234) needs the chart source on disk,
+  // which a repo-fetched render does not keep, so the gate here is the
+  // declared-inputs property, not a template analysis. An unpinned render's
+  // digest would be a function of the local helm binary — meaningless as an
+  // identity — so unpinned renders record neither digest.
+  const digests = profile
+    ? {
+        inputDigest: helmInputDigest({
+          // Same chart-reference convention helmInstall digests: a local
+          // path stays itself; a repo-fetched chart is `<repo-url>/<chart>`.
+          chart: props.repo ? `${props.repo}/${props.chart}` : props.chart,
+          chartVersion: props.version,
+          values: props.values ?? {},
+          capabilityProfile: {
+            kubeVersion: profile.kubeVersion,
+            apiVersions: profile.apiVersions,
+          },
+        }),
+        contentDigest: helmContentDigest(yamlText),
+        ...(valuesProbe ? { coalescedValuesDigest: valuesProbe.digest } : {}),
+      }
+    : {};
+
+  renderRecords.push({
+    name: props.name,
+    chart: props.chart,
+    version: props.version,
+    capabilityProfile: profile,
+    ...digests,
+  });
+
   const out: Record<string, InstanceType<typeof Deployment>> = {};
 
   if (props.createNamespace && props.namespace) {

package/src/skills/chant-helm.md

@@ -289,6 +289,13 @@ const lifecycle = HelmCRDLifecycle({
 | WHM407 | post-synth | Secret with inline data |
 | WHM501 | post-synth | Unused values keys |
 | WHM502 | post-synth | Deprecated K8s API versions |
+| WHM503 | pinned-render | Pinned render artifact carries populated Secret data/stringData — use `runtimeSlot()` or `HelmExternalSecret` |
+
+WHM503 is a different stage from the rest: it scans the STORED, rendered
+artifact a pinned `HelmRender` writes to the render store (#1238), not the
+chart source `WHM005`-`WHM502` validate. `WHM407` catches an inline literal
+in a chart TEMPLATE before rendering; WHM503 catches a resolved credential
+that made it into a durable, promotable artifact.
 
 ## OCI registry workflow