@intentius/chant-lexicon-helm 0.46.0 → 0.49.0

package/src/render-diff.ts

@@ -0,0 +1,407 @@
+/**
+ * Render diffing (#1249 offline, #1250 live — epic #1228 Phase 6), the two
+ * halves of `chant helm diff` (./commands.ts).
+ *
+ * `diffRenders` (#1249) is the offline half: given two content digests
+ * already in the render store (render-store.ts), report what changed
+ * between them — no cluster, no credentials, no live read. This is the
+ * pre-flight question a pin, a chart bump, or a values change all raise:
+ * "what will this touch?"
+ *
+ * Pairing is document-level, keyed on `(kind, namespace, name)` — the same
+ * identity `RenderManifest.documents` already indexes (render-store.ts).
+ * That index exists precisely so two renders can be matched without
+ * reparsing a whole stream: a document present on both sides with the same
+ * per-document digest is unchanged and costs nothing further; one whose
+ * digest differs is parsed on both sides and diffed field by field.
+ *
+ * Field-level diffing reuses core's `flattenDeepProperties` /
+ * `deepValueEqual` (packages/core/src/deep-observation.ts) — the same
+ * path-flattening core's own live-drift diff (lifecycle/deep-diff.ts) is
+ * built on. This module does not reuse `diffDeep` itself for the offline
+ * path: that function's shape is declared/live/baseline/fieldOwners,
+ * tailored to a source tree vs a cluster read. A stored render has neither
+ * a baseline nor a field owner, and both sides here are equally "declared"
+ * — reusing the flatten/compare primitives without the three-way apparatus
+ * is the right cut for render-to-render.
+ *
+ * Duplicate documents (an aliased dependency emitting the same CRD twice,
+ * render-digest.ts's canonicalization note) are matched positionally within
+ * their `(kind, namespace, name)` group: first occurrence to first, second
+ * to second. A group with more entries on one side reports the surplus as
+ * added or removed rather than guessing which duplicate corresponds to
+ * which.
+ *
+ * A document neither side's manifest could index (unparseable, or missing
+ * `kind`/`metadata.name` — render-store.ts's `indexRenderDocuments`) cannot
+ * be paired by identity. It is never silently dropped: `unindexed` counts
+ * it on whichever side(s) it appears, so a diff over two renders that both
+ * carry unindexable documents does not quietly under-report.
+ *
+ * `diffRenderLive` (#1250) is the online complement: given a single
+ * `contentDigest` resolved from the render store, read the live property
+ * tree for every document the render recorded — by identity
+ * (kind/namespace/name), not by helm release — and diff each one against
+ * the render's own stored bytes with `lifecycle/deep-diff.ts`. This *does*
+ * reuse `diffDeep`'s three-way apparatus (via `diffDeepObservation`): the
+ * declared side is the render's stored documents, the live side is a
+ * cluster read, which is exactly that function's shape.
+ *
+ * The declared side for the live path is the render's stored documents,
+ * never a fresh `helm template` run and never a chant TS build. A digest
+ * not in the store — an unpinned render was never persisted
+ * (`render-store.ts`'s `persistHelmRender` refuses that) — has nothing to
+ * diff against and comes back `found: false`, never a false "no drift" over
+ * documents nobody has (epic AC: unpinned releases handled without false
+ * drift).
+ *
+ * The live side reuses the exact seam `observeResourcesDeepHelm` (#1247)
+ * uses — the k8s lexicon's typed client and normalization hooks — so a
+ * document this reads and one a release's `describeResources` reads compare
+ * under the same rules (secret masking, managed-fields ownership, pruning).
+ * Hook resources need no special handling here the way the release-scoped
+ * read needs a second `helm get hooks` channel: `helm template` (what
+ * produced the stored render) already includes hook manifests as ordinary
+ * documents, so they are simply rows in `manifest.documents` like any other.
+ */
+
+import yaml from "js-yaml";
+
+import { deepValueEqual, flattenDeepProperties, normalizeDeepObservation } from "@intentius/chant/deep-observation";
+import type { DeepDiffResult } from "@intentius/chant/lifecycle/deep-diff";
+import { diffDeepObservation } from "@intentius/chant/lifecycle/deep-observe";
+import type { K8sConnector } from "@intentius/chant-lexicon-k8s/api/connect";
+import { observeResourcesDeepK8s } from "@intentius/chant-lexicon-k8s/deep-observe";
+import { gvkToTypeName } from "@intentius/chant-lexicon-k8s/spec/parse";
+
+import { helmDeepNormalizationHooks } from "./deep-observe-hooks";
+import { CLUSTER_SCOPED_KINDS } from "./release-observe";
+import { loadRenderManifest, readRenderDocument, type RenderDocumentEntry, type RenderManifest } from "./render-store";
+
+// ---------------------------------------------------------------------------
+// Offline: render-to-render (#1249)
+// ---------------------------------------------------------------------------
+
+/** How one field within a changed document differs between the two renders. */
+export interface RenderFieldChange {
+  /** Path within the document's property tree (`spec.replicas`, `data.zeta`). */
+  path: string;
+  /**
+   * `changed` — both renders have the path, with different values.
+   * `added` — only the right-hand (`to`) render has it.
+   * `removed` — only the left-hand (`from`) render has it.
+   */
+  kind: "changed" | "added" | "removed";
+  /** Value on the `from` side. Absent for `added`. */
+  before?: unknown;
+  /** Value on the `to` side. Absent for `removed`. */
+  after?: unknown;
+}
+
+/** Identity of one document, for reporting — the same triple documents are paired on. */
+export interface RenderDiffDocumentRef {
+  kind: string;
+  namespace: string | null;
+  name: string;
+  /** The `# Source:` origin path, when the document carried one. */
+  source: string | null;
+}
+
+/** A document present on only one side. */
+export interface AddedOrRemovedDocument extends RenderDiffDocumentRef {
+  digest: string;
+}
+
+/** A document present on both sides with different content. */
+export interface ChangedDocument extends RenderDiffDocumentRef {
+  /** Per-document digest on the `from` side. */
+  beforeDigest: string;
+  /** Per-document digest on the `to` side. */
+  afterDigest: string;
+  /** Field-level differences, sorted by path. Empty only if a document parses but yields no leaves. */
+  changes: RenderFieldChange[];
+}
+
+export interface RenderDiffResult {
+  from: { contentDigest: string; chart: string; releaseName: string };
+  to: { contentDigest: string; chart: string; releaseName: string };
+  /** Present only on `to`. Sorted by kind/namespace/name. */
+  added: AddedOrRemovedDocument[];
+  /** Present only on `from`. Sorted by kind/namespace/name. */
+  removed: AddedOrRemovedDocument[];
+  /** Present on both, different bytes. Sorted by kind/namespace/name. */
+  changed: ChangedDocument[];
+  /** Present on both with equal per-document digest — reported as identities only, no field pass run. */
+  unchanged: RenderDiffDocumentRef[];
+  /**
+   * Documents each manifest's index could not identify — present in the
+   * stream (`docCount`) but absent from `documents` (unparseable, or no
+   * `kind` + `metadata.name`). Never matched, never silently dropped.
+   */
+  unindexed: { from: number; to: number };
+}
+
+function docKey(doc: Pick<RenderDocumentEntry, "kind" | "namespace" | "name">): string {
+  return `${doc.kind}\0${doc.namespace ?? ""}\0${doc.name}`;
+}
+
+function docRef(doc: RenderDocumentEntry): RenderDiffDocumentRef {
+  return { kind: doc.kind, namespace: doc.namespace, name: doc.name, source: doc.source };
+}
+
+/** Group a manifest's document entries by identity, preserving occurrence order for duplicate matching. */
+function groupByIdentity(documents: readonly RenderDocumentEntry[]): Map<string, RenderDocumentEntry[]> {
+  const groups = new Map<string, RenderDocumentEntry[]>();
+  for (const doc of documents) {
+    const key = docKey(doc);
+    const group = groups.get(key);
+    if (group) group.push(doc);
+    else groups.set(key, [doc]);
+  }
+  return groups;
+}
+
+function compareRefs(a: RenderDiffDocumentRef, b: RenderDiffDocumentRef): number {
+  return (
+    a.kind.localeCompare(b.kind) ||
+    (a.namespace ?? "").localeCompare(b.namespace ?? "") ||
+    a.name.localeCompare(b.name)
+  );
+}
+
+/**
+ * Field-level diff between a document's two parsed trees. Both sides are
+ * flattened with `flattenDeepProperties` (no ordering hooks — a stored
+ * render carries no lexicon to supply one, so arrays are compared
+ * positionally, exactly as the canonicalized bytes ordered them) and walked
+ * path by path.
+ */
+function diffDocumentFields(beforeText: string, afterText: string, entityType: string): RenderFieldChange[] {
+  const beforeTree = (yaml.load(beforeText) ?? {}) as Record<string, unknown>;
+  const afterTree = (yaml.load(afterText) ?? {}) as Record<string, unknown>;
+  const beforeFlat = flattenDeepProperties(beforeTree, { entityType, side: "declared" });
+  const afterFlat = flattenDeepProperties(afterTree, { entityType, side: "live" });
+
+  const paths = [...new Set([...beforeFlat.keys(), ...afterFlat.keys()])].sort();
+  const changes: RenderFieldChange[] = [];
+  for (const path of paths) {
+    const hasBefore = beforeFlat.has(path);
+    const hasAfter = afterFlat.has(path);
+    const beforeValue = beforeFlat.get(path);
+    const afterValue = afterFlat.get(path);
+    if (hasBefore && hasAfter && deepValueEqual(beforeValue, afterValue)) continue;
+    const kind: RenderFieldChange["kind"] = !hasBefore ? "added" : !hasAfter ? "removed" : "changed";
+    changes.push({
+      path,
+      kind,
+      ...(hasBefore ? { before: beforeValue } : {}),
+      ...(hasAfter ? { after: afterValue } : {}),
+    });
+  }
+  return changes;
+}
+
+export interface DiffRendersOptions {
+  /** Render store root override; defaults to `renderStoreRoot()`. */
+  root?: string;
+}
+
+/**
+ * Diff two renders already in the store, by content digest. Offline: every
+ * byte compared comes from the archive (render-store.ts), never a cluster.
+ *
+ * Throws when either digest has no manifest — a diff over a render nobody
+ * persisted is a usage error, not an empty report.
+ */
+export function diffRenders(from: string, to: string, options?: DiffRendersOptions): RenderDiffResult {
+  const opts = { root: options?.root };
+  const fromManifest = requireManifest(from, opts.root);
+  const toManifest = requireManifest(to, opts.root);
+
+  const fromGroups = groupByIdentity(fromManifest.documents);
+  const toGroups = groupByIdentity(toManifest.documents);
+
+  const added: AddedOrRemovedDocument[] = [];
+  const removed: AddedOrRemovedDocument[] = [];
+  const changed: ChangedDocument[] = [];
+  const unchanged: RenderDiffDocumentRef[] = [];
+
+  const keys = new Set([...fromGroups.keys(), ...toGroups.keys()]);
+  for (const key of keys) {
+    const fromEntries = fromGroups.get(key) ?? [];
+    const toEntries = toGroups.get(key) ?? [];
+    const pairCount = Math.min(fromEntries.length, toEntries.length);
+
+    for (let i = 0; i < pairCount; i++) {
+      const fromDoc = fromEntries[i];
+      const toDoc = toEntries[i];
+      if (fromDoc.digest === toDoc.digest) {
+        unchanged.push(docRef(fromDoc));
+        continue;
+      }
+      const fromRead = readRenderDocument(from, fromDoc, opts);
+      const toRead = readRenderDocument(to, toDoc, opts);
+      /* c8 ignore next 5 -- indexed entries always resolve; defensive only */
+      if (!fromRead || !toRead) {
+        throw new Error(
+          `render diff: indexed document ${fromDoc.kind}/${fromDoc.name} failed to resolve from its own store entry`,
+        );
+      }
+      changed.push({
+        ...docRef(fromDoc),
+        beforeDigest: fromDoc.digest,
+        afterDigest: toDoc.digest,
+        changes: diffDocumentFields(fromRead.text, toRead.text, fromDoc.kind),
+      });
+    }
+    for (let i = pairCount; i < fromEntries.length; i++) {
+      removed.push({ ...docRef(fromEntries[i]), digest: fromEntries[i].digest });
+    }
+    for (let i = pairCount; i < toEntries.length; i++) {
+      added.push({ ...docRef(toEntries[i]), digest: toEntries[i].digest });
+    }
+  }
+
+  return {
+    from: { contentDigest: fromManifest.contentDigest, chart: fromManifest.chart, releaseName: fromManifest.releaseName },
+    to: { contentDigest: toManifest.contentDigest, chart: toManifest.chart, releaseName: toManifest.releaseName },
+    added: added.sort(compareRefs),
+    removed: removed.sort(compareRefs),
+    changed: changed.sort(compareRefs),
+    unchanged: unchanged.sort(compareRefs),
+    unindexed: {
+      from: fromManifest.docCount - fromManifest.documents.length,
+      to: toManifest.docCount - toManifest.documents.length,
+    },
+  };
+}
+
+function requireManifest(contentDigest: string, root?: string): RenderManifest {
+  const manifest = loadRenderManifest(contentDigest, { root });
+  if (!manifest) {
+    throw new Error(
+      `no stored render for ${contentDigest} — resolve it first (chant helm renders), or check ` +
+        `CHANT_HELM_RENDER_ROOT if the store root was overridden.`,
+    );
+  }
+  return manifest;
+}
+
+/** True when the diff found no added, removed, or changed documents. */
+export function renderDiffIsEmpty(result: RenderDiffResult): boolean {
+  return result.added.length === 0 && result.removed.length === 0 && result.changed.length === 0;
+}
+
+// ---------------------------------------------------------------------------
+// Live: render-to-live (#1250)
+// ---------------------------------------------------------------------------
+
+export interface RenderLiveDiffOptions {
+  /** The stored render to diff against the cluster — a `contentDigest` from `chant helm renders`. */
+  contentDigest: string;
+  /** The chant environment the live read targets — resolves the k8s cluster binding (`k8s.profiles.<environment>.context`), same as any other live read. */
+  environment: string;
+  /** Render store root override (tests); defaults to `renderStoreRoot()`. */
+  root?: string;
+  owned?: boolean;
+}
+
+export interface RenderLiveDiffDeps {
+  /** Forwarded to the k8s reader — a test passes a fake cluster's connector. */
+  connect?: K8sConnector;
+}
+
+export type RenderLiveDiffOutcome =
+  | { found: true; manifest: RenderManifest; diff: DeepDiffResult }
+  /** No such render in the store — refuse the diff rather than report a false clean result. */
+  | { found: false; contentDigest: string };
+
+function splitApiVersion(apiVersion: string): { group: string; version: string } {
+  const slash = apiVersion.indexOf("/");
+  return slash > 0
+    ? { group: apiVersion.slice(0, slash), version: apiVersion.slice(slash + 1) }
+    : { group: "", version: apiVersion };
+}
+
+/** Row key convention shared with the release-scoped reads (#1246/#1247): `<Kind>/<namespace>/<name>`, `cluster:<Kind>/<name>`. */
+export function documentKey(kind: string, namespace: string | undefined, name: string): string {
+  return namespace ? `${kind}/${namespace}/${name}` : `cluster:${kind}/${name}`;
+}
+
+/**
+ * A namespace-silent document defaults to the render's target namespace —
+ * the same rule a deployed release applies to its manifest (`helm apply
+ * -n <ns>` targets whatever a namespace-silent object's `.Release.Namespace`
+ * would have filled in) — unless the kind is cluster-scoped, in which case a
+ * missing namespace is never defaulted.
+ */
+export function resolveDocumentNamespace(
+  kind: string,
+  declared: string | null,
+  renderNamespace: string | null,
+): string | undefined {
+  if (declared) return declared;
+  if (CLUSTER_SCOPED_KINDS.has(kind)) return undefined;
+  return renderNamespace ?? undefined;
+}
+
+/** The document minus the envelope the row's `type` already carries — mirrors `deep-observe.ts`'s `declaredTreeOf`. */
+function declaredTreeOf(doc: Record<string, unknown>, namespace: string | undefined): Record<string, unknown> {
+  const { apiVersion: _apiVersion, kind: _kind, ...rest } = doc;
+  const metadata = (rest.metadata ?? {}) as Record<string, unknown>;
+  return {
+    ...rest,
+    ...(namespace ? { metadata: { ...metadata, ...(metadata.namespace === undefined ? { namespace } : {}) } } : {}),
+  };
+}
+
+/**
+ * Diff one stored render's documents against the live cluster.
+ *
+ * `found: false` when `contentDigest` is not in the store — never fabricates
+ * a document, and never reports "no drift" over a render this has no bytes
+ * for. On a found render, every document indexed in its manifest becomes a
+ * synthetic declared entity (keyed like a release's rows), read live through
+ * the k8s lexicon's deep observer, and diffed property-by-property.
+ */
+export async function diffRenderLive(
+  options: RenderLiveDiffOptions,
+  deps: RenderLiveDiffDeps = {},
+): Promise<RenderLiveDiffOutcome> {
+  const manifest = loadRenderManifest(options.contentDigest, { root: options.root });
+  if (!manifest) return { found: false, contentDigest: options.contentDigest };
+
+  const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+  for (const docEntry of manifest.documents) {
+    const resolved = readRenderDocument(
+      options.contentDigest,
+      { kind: docEntry.kind, name: docEntry.name, namespace: docEntry.namespace },
+      { root: options.root },
+    );
+    if (!resolved) continue; // integrity gap between the index and the content — skip, never fabricate
+    const parsed: unknown = yaml.load(resolved.text);
+    if (parsed === null || typeof parsed !== "object") continue;
+    const namespace = resolveDocumentNamespace(docEntry.kind, docEntry.namespace, manifest.namespace);
+    const key = documentKey(docEntry.kind, namespace, docEntry.name);
+    const { group, version } = splitApiVersion(docEntry.apiVersion);
+    entities.set(key, {
+      entityType: gvkToTypeName({ group, version, kind: docEntry.kind }),
+      props: declaredTreeOf(parsed as Record<string, unknown>, namespace),
+    });
+  }
+
+  const k8sOptions = {
+    environment: options.environment,
+    buildOutput: "",
+    entityNames: [...entities.keys()],
+    entities,
+    ...(options.owned !== undefined ? { owned: options.owned } : {}),
+  };
+  const raw = deps.connect
+    ? await observeResourcesDeepK8s(k8sOptions, deps.connect)
+    : await observeResourcesDeepK8s(k8sOptions);
+  const live = normalizeDeepObservation(raw);
+  const diff = diffDeepObservation(entities, live, helmDeepNormalizationHooks);
+
+  return { found: true, manifest, diff };
+}

package/src/render-digest.test.ts

@@ -0,0 +1,186 @@
+import { describe, test, expect } from "vitest";
+import { createHash } from "node:crypto";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  canonicalizeRender,
+  helmContentDigest,
+  helmInputDigest,
+  renderStability,
+} from "./render-digest";
+import { helmInstallInputDigest } from "./op/activities/helm";
+import type { HelmRenderRecord } from "./render";
+
+const RENDERED = `---
+# Source: tiny-chart/templates/service.yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: rel-tiny
+spec:
+  selector:
+    app: rel
+  ports:
+  - port: 80
+---
+# Source: tiny-chart/templates/deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: rel-tiny
+spec:
+  replicas: 1
+`;
+
+describe("canonicalizeRender", () => {
+  test("mapping key order is normalized; two key orders canonicalize identically", () => {
+    const a = "---\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: cm\ndata:\n  x: \"1\"\n";
+    const b = "---\nkind: ConfigMap\ndata:\n  x: \"1\"\nmetadata:\n  name: cm\napiVersion: v1\n";
+    expect(canonicalizeRender(a)).toBe(canonicalizeRender(b));
+  });
+
+  test("sequence order is preserved — list order is meaningful to Kubernetes", () => {
+    const a = "---\nkind: ConfigMap\napiVersion: v1\nitems:\n- one\n- two\n";
+    const b = "---\nkind: ConfigMap\napiVersion: v1\nitems:\n- two\n- one\n";
+    expect(canonicalizeRender(a)).not.toBe(canonicalizeRender(b));
+  });
+
+  test("document order is preserved, not sorted", () => {
+    const svc = "# Source: c/templates/s.yaml\napiVersion: v1\nkind: Service\nmetadata:\n  name: s\n";
+    const dep = "# Source: c/templates/d.yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: d\n";
+    const ab = canonicalizeRender(`---\n${svc}---\n${dep}`);
+    const ba = canonicalizeRender(`---\n${dep}---\n${svc}`);
+    expect(ab).not.toBe(ba);
+    // Same documents either way — only the order differs.
+    expect(ab.split("---\n").sort()).toEqual(ba.split("---\n").sort());
+  });
+
+  test("duplicate documents are preserved, and the form is stable across calls", () => {
+    const crd =
+      "# Source: c/charts/kid/crds/kid.yaml\napiVersion: apiextensions.k8s.io/v1\nkind: CustomResourceDefinition\nmetadata:\n  name: kidthings.example.com\n";
+    const doubled = `---\n${crd}---\n${crd}`;
+    const canonical = canonicalizeRender(doubled);
+    expect(canonical.match(/kidthings\.example\.com/g)?.length).toBe(2);
+    expect(canonicalizeRender(doubled)).toBe(canonical);
+  });
+
+  test("render noise is normalized: CRLF, trailing whitespace, non-Source comments, empty documents", () => {
+    const noisy =
+      "---\r\n# Source: c/templates/cm.yaml\r\nkind: ConfigMap   \r\napiVersion: v1\r\n# helm inserted this remark\r\nmetadata:\r\n  name: cm  \r\n---\r\n# Source: c/templates/empty.yaml\r\n---\r\n";
+    const clean =
+      "---\n# Source: c/templates/cm.yaml\nkind: ConfigMap\napiVersion: v1\nmetadata:\n  name: cm\n";
+    expect(canonicalizeRender(noisy)).toBe(canonicalizeRender(clean));
+  });
+
+  test("the # Source: header survives as the document's leading line", () => {
+    const canonical = canonicalizeRender(RENDERED);
+    expect(canonical).toContain("---\n# Source: tiny-chart/templates/service.yaml\napiVersion: v1\n");
+    expect(canonical).toContain("---\n# Source: tiny-chart/templates/deployment.yaml\napiVersion: apps/v1\n");
+  });
+});
+
+describe("helmContentDigest", () => {
+  test("pinned against a hand-written canonical form — the cross-machine anchor", () => {
+    const rendered = "---\n# Source: c/templates/cm.yaml\nkind: ConfigMap\ndata:\n  b: '2'\n  a: '1'\napiVersion: v1\nmetadata:\n  name: cm\n";
+    // Independently derived: sorted keys, 2-space indent, one trailing
+    // newline. Knowing the exact bytes without calling canonicalizeRender
+    // makes this a non-circular reproducibility anchor: any machine, any
+    // platform, must produce this digest for this input.
+    const canonical =
+      "---\n# Source: c/templates/cm.yaml\napiVersion: v1\ndata:\n  a: '1'\n  b: '2'\nkind: ConfigMap\nmetadata:\n  name: cm\n";
+    expect(canonicalizeRender(rendered)).toBe(canonical);
+    const expected = `sha256:${createHash("sha256").update(canonical, "utf8").digest("hex")}`;
+    expect(helmContentDigest(rendered)).toBe(expected);
+  });
+
+  test("changes when the rendered content changes", () => {
+    const one = RENDERED;
+    const three = RENDERED.replace("replicas: 1", "replicas: 3");
+    expect(helmContentDigest(one)).not.toBe(helmContentDigest(three));
+  });
+
+  test("full sha256: prefix, 64 hex characters", () => {
+    expect(helmContentDigest(RENDERED)).toMatch(/^sha256:[0-9a-f]{64}$/);
+  });
+});
+
+describe("helmInputDigest", () => {
+  test("agrees with helmInstallInputDigest (#1243) for the same inputs", () => {
+    const values = { replicaCount: 3, image: { tag: "v1" } };
+    const dir = mkdtempSync(join(tmpdir(), "chant-helm-digest-"));
+    const valuesFile = join(dir, "values.yaml");
+    writeFileSync(valuesFile, "replicaCount: 3\nimage:\n  tag: v1\n");
+
+    const fromRenderSide = helmInputDigest({
+      chart: "./chart",
+      chartVersion: "1.2.3",
+      values,
+      capabilityProfile: { kubeVersion: "1.33.6", apiVersions: ["batch/v1", "apps/v1"] },
+    });
+    const fromDeploySide = helmInstallInputDigest({
+      name: "web",
+      chart: "./chart",
+      chartVersion: "1.2.3",
+      values: valuesFile,
+      capabilityProfile: { kubeVersion: "1.33.6", apiVersions: ["apps/v1", "batch/v1"] },
+    });
+    expect(fromRenderSide).toBe(fromDeploySide);
+  });
+
+  test("the profile's facts join the digest; its name would not (the shape has no name field)", () => {
+    const base = { chart: "./chart", chartVersion: "1.0.0", values: {} };
+    const bare = helmInputDigest(base);
+    const pinned = helmInputDigest({
+      ...base,
+      capabilityProfile: { kubeVersion: "1.33.6" },
+    });
+    expect(pinned).not.toBe(bare);
+    expect(pinned).toMatch(/^sha256:[0-9a-f]{64}$/);
+  });
+});
+
+function record(overrides: Partial<HelmRenderRecord> & { name: string }): HelmRenderRecord {
+  return { chart: "c", version: "1.0.0", ...overrides };
+}
+
+describe("renderStability", () => {
+  test("same inputDigest, different contentDigest — flagged as unstable", () => {
+    const report = renderStability([
+      record({ name: "eso", inputDigest: "sha256:aa", contentDigest: "sha256:11" }),
+      record({ name: "eso", inputDigest: "sha256:aa", contentDigest: "sha256:22" }),
+    ]);
+    expect(report.unstable).toEqual([
+      { inputDigest: "sha256:aa", names: ["eso", "eso"], contentDigests: ["sha256:11", "sha256:22"] },
+    ]);
+    expect(report.stable).toEqual([]);
+  });
+
+  test("same inputDigest, same contentDigest — stable", () => {
+    const report = renderStability([
+      record({ name: "eso", inputDigest: "sha256:aa", contentDigest: "sha256:11" }),
+      record({ name: "eso", inputDigest: "sha256:aa", contentDigest: "sha256:11" }),
+    ]);
+    expect(report.stable.length).toBe(1);
+    expect(report.unstable).toEqual([]);
+  });
+
+  test("different names never group together — the release name is a real render input", () => {
+    const report = renderStability([
+      record({ name: "a", inputDigest: "sha256:aa", contentDigest: "sha256:11" }),
+      record({ name: "b", inputDigest: "sha256:aa", contentDigest: "sha256:22" }),
+    ]);
+    expect(report.unstable).toEqual([]);
+    expect(report.stable.length).toBe(2);
+  });
+
+  test("unpinned records (no digests) are unassessed, never stable by omission", () => {
+    const report = renderStability([
+      record({ name: "unpinned" }),
+      record({ name: "eso", inputDigest: "sha256:aa", contentDigest: "sha256:11" }),
+    ]);
+    expect(report.unassessed).toEqual(["unpinned"]);
+    expect(report.stable.length).toBe(1);
+  });
+});