@intentius/chant-lexicon-helm 0.46.0 → 0.49.0

package/src/render-digest.ts

@@ -0,0 +1,207 @@
+/**
+ * Render canonicalization and the contentDigest/inputDigest split
+ * (#1237, epic #1228 Phase 2).
+ *
+ * A pinned render's output is normalized to a canonical byte form before
+ * digesting, and two digests are recorded with different jobs:
+ *
+ * - `inputDigest` answers "same inputs?" cheaply — a `sha256:` over the
+ *   canonical JSON of { chart reference, chart version, resolved values,
+ *   capability profile }. It is the same digest `helmInstall` records in the
+ *   release ledger (#1243), computed by the same helper, so a render and a
+ *   deploy of the same inputs share an identity.
+ * - `contentDigest` answers "same bytes on the cluster?" — a `sha256:` over
+ *   the canonical rendered bytes. It is the artifact identity.
+ *
+ * The two diverge exactly when rendering is unpinned or the chart is
+ * unstable: two renders with the same inputDigest but different
+ * contentDigests mean the render function is not a function of its declared
+ * inputs. That divergence is itself a signal — `renderStability` names it.
+ *
+ * Canonicalization scope (what the epic measured, not more):
+ * - Mapping key order is normalized (sorted) — YAML mappings are unordered
+ *   in Kubernetes semantics, so key order is render noise. Sequence order is
+ *   never touched; list order is meaningful to Kubernetes.
+ * - Document order is preserved, not sorted. The epic verified document
+ *   ordering is already stable across renders (three renders, again with
+ *   subcharts), so reordering would only destroy information.
+ * - Duplicate documents are preserved. An aliased dependency emits the same
+ *   CRD twice (epic finding 11); helm dedupes on install, the artifact keeps
+ *   both, and the digest stays stable because canonicalization is
+ *   per-document and order-preserving.
+ * - The helm-inserted `# Source:` header is kept (it is the origin-routing
+ *   key the archive wrapper builds on) and normalized to a single leading
+ *   line. All other comments, trailing whitespace, CRLF line endings, and
+ *   document-separator styling are render noise and are dropped or
+ *   normalized.
+ */
+
+import { createHash } from "node:crypto";
+
+import { canonicalJson } from "@intentius/chant/effect-receipt";
+import yaml from "js-yaml";
+
+import { splitDocuments } from "./pinnability/render-stream";
+import type { HelmRenderRecord } from "./render";
+
+/**
+ * The declared inputs of a helm render or deploy, in the exact shape #1243
+ * digests for the release ledger. `helmInstallInputDigest`
+ * (op/activities/helm.ts) and `HelmRender`'s recorded `inputDigest` both
+ * delegate here, so the two cannot drift: the same chart reference, version,
+ * resolved values, and capability facts produce the same digest whether they
+ * reach helm through a render or a deploy.
+ */
+export interface HelmInputDigestSource {
+  /** Chart reference — a local path, or `<repo-url>/<chart>` for repo-fetched charts. */
+  chart: string;
+  /** Pinned chart version. Digested as `null` when absent. */
+  chartVersion?: string;
+  /** Resolved values (file merged with overrides). Digested as `{}` when absent. */
+  values?: Record<string, unknown>;
+  /**
+   * Capability facts the render is pinned against. Only the facts join the
+   * digest — the profile's *name* is a label, not an input, so two profiles
+   * declaring the same cluster digest identically. `apiVersions` is sorted:
+   * it declares a set, not an order.
+   */
+  capabilityProfile?: { kubeVersion?: string; apiVersions?: string[] };
+}
+
+/**
+ * The input-side identity of a helm render or deploy: `sha256:` over the
+ * canonical JSON (core's `canonicalJson`, RFC 8785 shape) of the declared
+ * inputs. Shared with #1243's release-ledger digest — see
+ * `HelmInputDigestSource`. Deliberately excludes the release name and
+ * namespace: those are baked into the rendered bytes but the ledger uses
+ * this digest as a cross-environment join key, and two environments
+ * deploying the same chart, version, and values must share it.
+ */
+export function helmInputDigest(source: HelmInputDigestSource): string {
+  const input: Record<string, unknown> = {
+    chart: source.chart,
+    chartVersion: source.chartVersion ?? null,
+    values: source.values ?? {},
+  };
+  if (source.capabilityProfile) {
+    input.capabilityProfile = {
+      kubeVersion: source.capabilityProfile.kubeVersion ?? null,
+      apiVersions: [...(source.capabilityProfile.apiVersions ?? [])].sort(),
+    };
+  }
+  return `sha256:${createHash("sha256").update(canonicalJson(input), "utf8").digest("hex")}`;
+}
+
+/** The helm-inserted origin header, e.g. `# Source: chart/templates/deploy.yaml`. */
+const SOURCE_HEADER = /^# Source: \S+$/m;
+
+/**
+ * Normalize a `helm template` stream to its canonical byte form.
+ *
+ * Per document: the `# Source:` header (if any) becomes the single leading
+ * comment line, the YAML body is re-serialized with sorted mapping keys
+ * (sequences untouched), no line-width folding, and a trailing newline.
+ * Documents are emitted in render order, each introduced by a `---` line.
+ * CRLF endings, trailing whitespace, non-Source comments, and empty or
+ * comment-only documents are render noise and do not survive.
+ *
+ * A document that fails to parse as YAML is kept verbatim (trimmed) rather
+ * than dropped — the canonical form must never silently lose content, and a
+ * verbatim document still digests deterministically.
+ */
+export function canonicalizeRender(rendered: string): string {
+  const out: string[] = [];
+  for (const doc of splitDocuments(rendered.replace(/\r\n/g, "\n"))) {
+    const header = doc.match(SOURCE_HEADER)?.[0];
+    let parsed: unknown;
+    let parseFailed = false;
+    try {
+      parsed = yaml.load(doc);
+    } catch {
+      parseFailed = true;
+    }
+    if (parseFailed) {
+      out.push(`---\n${doc}\n`);
+      continue;
+    }
+    if (parsed === null || parsed === undefined) continue; // comment-only or empty document
+    const body = yaml.dump(parsed, { sortKeys: true, lineWidth: -1, noRefs: true });
+    out.push(`---\n${header ? header + "\n" : ""}${body}`);
+  }
+  return out.join("");
+}
+
+/**
+ * The content-side identity of a render: `sha256:` over the canonical bytes
+ * of the rendered stream (see `canonicalizeRender`). Unlike `inputDigest`,
+ * this changes whenever the bytes that would reach the cluster change — a
+ * chart upgrade with identical values, a helm version that renders
+ * differently, an unstable template.
+ */
+export function helmContentDigest(rendered: string): string {
+  return `sha256:${createHash("sha256").update(canonicalizeRender(rendered), "utf8").digest("hex")}`;
+}
+
+/** One inputDigest's renders and the distinct content identities they produced. */
+export interface RenderStabilityGroup {
+  inputDigest: string;
+  /** Render names in this group, in record order. */
+  names: string[];
+  /** Distinct content digests observed, in first-seen order. */
+  contentDigests: string[];
+}
+
+export interface RenderStabilityReport {
+  /** Groups whose every render produced the same bytes. */
+  stable: RenderStabilityGroup[];
+  /**
+   * Groups where the same inputs produced different bytes: the render is
+   * not pinned down by its declared inputs — an unstable chart, or an input
+   * that escaped declaration. Every group here is a defect signal.
+   */
+  unstable: RenderStabilityGroup[];
+  /** Names of records carrying no digests (unpinned renders) — unassessable. */
+  unassessed: string[];
+}
+
+/**
+ * Group recorded renders by input identity and report whether the same
+ * inputs always produced the same bytes.
+ *
+ * Two renders with equal `inputDigest` and different `contentDigest` mean
+ * the render is not a function of its declared inputs — the chart is
+ * unstable (generated values, timestamps) or an input escaped declaration.
+ * That divergence is the signal this helper exists to name; a single render
+ * per input proves nothing and lands in `stable` by default.
+ *
+ * Grouping keys on `(inputDigest, name)` because the release name is a real
+ * render input baked into the bytes but deliberately absent from
+ * `inputDigest` (see `helmInputDigest`) — two differently named renders of
+ * the same chart legitimately differ in content and must not be read as
+ * instability.
+ */
+export function renderStability(records: readonly HelmRenderRecord[]): RenderStabilityReport {
+  const groups = new Map<string, RenderStabilityGroup>();
+  const unassessed: string[] = [];
+  for (const record of records) {
+    if (!record.inputDigest || !record.contentDigest) {
+      unassessed.push(record.name);
+      continue;
+    }
+    const key = `${record.inputDigest}${record.name}`;
+    let group = groups.get(key);
+    if (!group) {
+      group = { inputDigest: record.inputDigest, names: [], contentDigests: [] };
+      groups.set(key, group);
+    }
+    group.names.push(record.name);
+    if (!group.contentDigests.includes(record.contentDigest)) {
+      group.contentDigests.push(record.contentDigest);
+    }
+  }
+  const report: RenderStabilityReport = { stable: [], unstable: [], unassessed };
+  for (const group of groups.values()) {
+    (group.contentDigests.length > 1 ? report.unstable : report.stable).push(group);
+  }
+  return report;
+}

package/src/render-store.test.ts

@@ -0,0 +1,412 @@
+import { describe, test, expect, beforeAll, beforeEach, afterEach } from "vitest";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { tmpdir } from "node:os";
+
+import yaml from "js-yaml";
+
+import { HelmRender, clearHelmRenderRecords, getHelmRenderRecords } from "./render";
+import { canonicalizeRender, helmContentDigest, helmInputDigest } from "./render-digest";
+import {
+  findRenderByCacheKey,
+  helmValuesDigest,
+  indexRenderDocuments,
+  listRenderManifests,
+  loadRenderContent,
+  loadRenderManifest,
+  persistHelmRender,
+  readRenderDocument,
+  renderCacheKey,
+} from "./render-store";
+import type { HelmCapabilityProfile } from "./config";
+
+/**
+ * A raw `helm template`-shaped stream with deliberate render noise: CRLF
+ * endings, unsorted mapping keys, a comment-only document, and a duplicate
+ * document (epic finding 11 — an aliased dependency emits the same CRD
+ * twice).
+ */
+const RENDERED = [
+  "---",
+  "# Source: tiny/templates/serviceaccount.yaml",
+  "kind: ServiceAccount",
+  "apiVersion: v1",
+  "metadata:",
+  "  namespace: web",
+  "  name: tiny-sa",
+  "---",
+  "# comment-only document",
+  "---",
+  "# Source: tiny/templates/configmap.yaml\r",
+  "apiVersion: v1\r",
+  "kind: ConfigMap",
+  "metadata:",
+  "  name: tiny-config",
+  "  namespace: web",
+  "data:",
+  "  zeta: last",
+  "  alpha: first",
+  "---",
+  "# Source: tiny/crds/widgets.yaml",
+  "apiVersion: apiextensions.k8s.io/v1",
+  "kind: CustomResourceDefinition",
+  "metadata:",
+  "  name: widgets.example.com",
+  "spec:",
+  "  group: example.com",
+  "---",
+  "# Source: tiny/crds/widgets.yaml",
+  "apiVersion: apiextensions.k8s.io/v1",
+  "kind: CustomResourceDefinition",
+  "metadata:",
+  "  name: widgets.example.com",
+  "spec:",
+  "  group: example.com",
+  "",
+].join("\n");
+
+const PROFILE: HelmCapabilityProfile = {
+  name: "prod",
+  kubeVersion: "1.33.6",
+  apiVersions: ["batch/v1"],
+};
+
+const VALUES = { replicaCount: 3 };
+
+function freshRoot(): string {
+  return mkdtempSync(join(tmpdir(), "chant-helm-render-store-"));
+}
+
+function persistFixture(root: string, overrides?: Partial<Parameters<typeof persistHelmRender>[0]>) {
+  return persistHelmRender({
+    rendered: RENDERED,
+    releaseName: "rel",
+    chart: "tiny",
+    repo: "https://charts.example.com",
+    chartVersion: "0.1.0",
+    namespace: "web",
+    values: VALUES,
+    capabilityProfile: PROFILE,
+    helmVersion: "v4.1.1",
+    sourceRef: "deadbeef",
+    root,
+    ...overrides,
+  });
+}
+
+describe("persistHelmRender / render store", () => {
+  test("round-trip: persisted bytes load back byte-identical, and canonicalization is idempotent over them", () => {
+    const root = freshRoot();
+    const { manifest } = persistFixture(root);
+
+    const stored = loadRenderContent(manifest.contentDigest, { root });
+    expect(stored).toBe(canonicalizeRender(RENDERED));
+
+    // The store serves canonical bytes back as the cache — re-canonicalizing
+    // and re-digesting them must be a fixed point, or a cache hit would
+    // change the render's recorded identity.
+    expect(canonicalizeRender(stored!)).toBe(stored);
+    expect(helmContentDigest(stored!)).toBe(manifest.contentDigest);
+  });
+
+  test("the manifest records every field: identity, inputs, profile, index, provenance", () => {
+    const root = freshRoot();
+    const now = () => new Date("2026-08-24T12:00:00.000Z");
+    const { manifest, dir } = persistFixture(root, { now });
+
+    expect(manifest.version).toBe(1);
+    expect(manifest.chart).toBe("tiny");
+    expect(manifest.chartVersion).toBe("0.1.0");
+    expect(manifest.repo).toBe("https://charts.example.com");
+    expect(manifest.releaseName).toBe("rel");
+    expect(manifest.namespace).toBe("web");
+    expect(manifest.valuesDigest).toBe(helmValuesDigest(VALUES));
+    expect(manifest.inputDigest).toBe(
+      helmInputDigest({
+        chart: "https://charts.example.com/tiny",
+        chartVersion: "0.1.0",
+        values: VALUES,
+        capabilityProfile: { kubeVersion: "1.33.6", apiVersions: ["batch/v1"] },
+      }),
+    );
+    expect(manifest.capabilityProfile).toEqual({
+      cluster: "prod",
+      kubeVersion: "1.33.6",
+      apiVersions: ["batch/v1"],
+    });
+    expect(manifest.contentDigest).toBe(helmContentDigest(RENDERED));
+    // 4 canonical documents: the comment-only one is render noise and does
+    // not survive canonicalization; the duplicate CRD does (finding 11).
+    expect(manifest.docCount).toBe(4);
+    expect(manifest.documents.length).toBe(4);
+    expect(manifest.renderedAt).toBe("2026-08-24T12:00:00.000Z");
+    expect(manifest.helmVersion).toBe("v4.1.1");
+    expect(manifest.chantVersion).toMatch(/^\d+\.\d+\.\d+/);
+    expect(manifest.sourceRef).toBe("deadbeef");
+
+    // What landed on disk is the manifest itself, next to the bytes.
+    expect(dir).toBe(join(root, manifest.contentDigest.replace(":", "-")));
+    const onDisk = JSON.parse(readFileSync(join(dir, "manifest.json"), "utf8"));
+    expect(onDisk).toEqual(manifest);
+  });
+
+  test("an unpinned render is refused with the specific reason", () => {
+    const root = freshRoot();
+    expect(() => persistFixture(root, { capabilityProfile: undefined })).toThrow(
+      /no capability profile is declared.*no stable content identity/s,
+    );
+    // Nothing was written.
+    expect(readdirSync(root)).toEqual([]);
+  });
+
+  test("two renders with the same contentDigest share one store entry", () => {
+    const root = freshRoot();
+    const first = persistFixture(root, { now: () => new Date("2026-08-24T12:00:00.000Z") });
+    expect(first.deduplicated).toBe(false);
+
+    // Same bytes, later clock, different declared release inputs that do
+    // not change the bytes' identity: the content entry is reused untouched.
+    const second = persistFixture(root, { now: () => new Date("2026-08-25T09:00:00.000Z") });
+    expect(second.deduplicated).toBe(true);
+    expect(second.dir).toBe(first.dir);
+    // First writer wins — the stored manifest is immutable.
+    expect(second.manifest.renderedAt).toBe("2026-08-24T12:00:00.000Z");
+
+    const entries = readdirSync(root).filter((e) => e.startsWith("sha256-"));
+    expect(entries.length).toBe(1);
+    expect(listRenderManifests({ root }).length).toBe(1);
+  });
+
+  test("the document index resolves kind/namespace/name to that document's exact bytes", () => {
+    const root = freshRoot();
+    const { manifest } = persistFixture(root);
+
+    const hit = readRenderDocument(
+      manifest.contentDigest,
+      { kind: "ConfigMap", namespace: "web", name: "tiny-config" },
+      { root },
+    );
+    expect(hit).toBeDefined();
+    expect(hit!.entry.apiVersion).toBe("v1");
+    expect(hit!.entry.source).toBe("tiny/templates/configmap.yaml");
+    const doc = yaml.load(hit!.text) as { kind: string; data: Record<string, string> };
+    expect(doc.kind).toBe("ConfigMap");
+    expect(doc.data).toEqual({ zeta: "last", alpha: "first" });
+    // The bytes are the manifest-indexed slice of the stored content.
+    const content = loadRenderContent(manifest.contentDigest, { root })!;
+    expect(hit!.text).toBe(
+      Buffer.from(content, "utf8")
+        .subarray(hit!.entry.start, hit!.entry.start + hit!.entry.length)
+        .toString("utf8"),
+    );
+
+    // Cluster-scoped documents resolve with no namespace.
+    const crd = readRenderDocument(
+      manifest.contentDigest,
+      { kind: "CustomResourceDefinition", name: "widgets.example.com" },
+      { root },
+    );
+    expect(crd).toBeDefined();
+    expect(crd!.entry.namespace).toBeNull();
+
+    // A document the render never contained resolves to nothing.
+    expect(
+      readRenderDocument(manifest.contentDigest, { kind: "Secret", name: "nope" }, { root }),
+    ).toBeUndefined();
+  });
+
+  test("the inputs index resolves the full-inputs key to the stored digests", () => {
+    const root = freshRoot();
+    const { manifest } = persistFixture(root);
+
+    const key = renderCacheKey({
+      chart: "https://charts.example.com/tiny",
+      chartVersion: "0.1.0",
+      releaseName: "rel",
+      namespace: "web",
+      values: VALUES,
+      capabilityProfile: PROFILE,
+    });
+    const entry = findRenderByCacheKey(key, { root });
+    expect(entry).toEqual({
+      version: 1,
+      inputDigest: manifest.inputDigest,
+      contentDigest: manifest.contentDigest,
+    });
+
+    // The release name is part of the cache key even though inputDigest
+    // excludes it — it is baked into the bytes via .Release.Name.
+    const otherName = renderCacheKey({
+      chart: "https://charts.example.com/tiny",
+      chartVersion: "0.1.0",
+      releaseName: "other",
+      namespace: "web",
+      values: VALUES,
+      capabilityProfile: PROFILE,
+    });
+    expect(otherName).not.toBe(key);
+    expect(findRenderByCacheKey(otherName, { root })).toBeUndefined();
+  });
+
+  test("listRenderManifests lists every stored render and skips corrupt entries", () => {
+    const root = freshRoot();
+    const a = persistFixture(root);
+    const b = persistFixture(root, { rendered: RENDERED + "---\nkind: Secret\napiVersion: v1\nmetadata:\n  name: extra\n" });
+    expect(a.manifest.contentDigest).not.toBe(b.manifest.contentDigest);
+
+    // A corrupt entry must not fail the listing.
+    const corrupt = join(root, `sha256-${"f".repeat(64)}`);
+    mkdirSync(corrupt, { recursive: true });
+    writeFileSync(join(corrupt, "manifest.json"), "{not json");
+
+    const listed = listRenderManifests({ root });
+    expect(listed.map((m) => m.contentDigest).sort()).toEqual(
+      [a.manifest.contentDigest, b.manifest.contentDigest].sort(),
+    );
+  });
+
+  test("indexRenderDocuments counts every canonical document, indexed or not", () => {
+    const canonical = canonicalizeRender(RENDERED);
+    const { documents, docCount } = indexRenderDocuments(canonical);
+    expect(docCount).toBe(4);
+    // The duplicate CRD appears twice in the index, at different offsets.
+    const crds = documents.filter((d) => d.kind === "CustomResourceDefinition");
+    expect(crds.length).toBe(2);
+    expect(crds[0].start).not.toBe(crds[1].start);
+    expect(crds[0].digest).toBe(crds[1].digest);
+  });
+});
+
+/**
+ * HelmRender integration — asserted against a scripted `helm` double (the
+ * same pattern render.test.ts uses) so these tests need no real helm, no
+ * network, and no chart. The double answers `helm version` and answers any
+ * `helm template` with two small manifests, counting its template
+ * invocations so cache hits are observable.
+ */
+describe("HelmRender persistence (#1238)", () => {
+  const FAKE_BIN = join(tmpdir(), "chant-helm-render-store-fake-bin");
+  let storeRoot: string;
+  let countFile: string;
+  let origPath: string | undefined;
+  let origRoot: string | undefined;
+
+  beforeAll(() => {
+    mkdirSync(FAKE_BIN, { recursive: true });
+    writeFileSync(
+      join(FAKE_BIN, "helm"),
+      `#!/bin/sh
+if [ "$1" = "version" ]; then
+  echo "v4.1.1-fake"
+  exit 0
+fi
+echo x >> "$CHANT_TEST_HELM_TEMPLATE_COUNT"
+cat <<'EOF'
+---
+# Source: tiny/templates/configmap.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: fake-render
+  namespace: web
+data:
+  b: two
+  a: one
+---
+# Source: tiny/templates/serviceaccount.yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: fake-sa
+  namespace: web
+EOF
+`,
+      { mode: 0o755 },
+    );
+  });
+
+  beforeEach(() => {
+    storeRoot = freshRoot();
+    countFile = join(mkdtempSync(join(tmpdir(), "chant-helm-count-")), "count.txt");
+    process.env.CHANT_TEST_HELM_TEMPLATE_COUNT = countFile;
+    origRoot = process.env.CHANT_HELM_RENDER_ROOT;
+    process.env.CHANT_HELM_RENDER_ROOT = storeRoot;
+    origPath = process.env.PATH;
+    process.env.PATH = FAKE_BIN + delimiter + (origPath ?? "");
+    clearHelmRenderRecords();
+  });
+
+  afterEach(() => {
+    process.env.PATH = origPath;
+    if (origRoot === undefined) delete process.env.CHANT_HELM_RENDER_ROOT;
+    else process.env.CHANT_HELM_RENDER_ROOT = origRoot;
+    delete process.env.CHANT_TEST_HELM_TEMPLATE_COUNT;
+  });
+
+  function templateInvocations(): number {
+    if (!existsSync(countFile)) return 0;
+    return readFileSync(countFile, "utf8").split("\n").filter((l) => l.length > 0).length;
+  }
+
+  const pinnedProps = () =>
+    ({
+      name: "rel",
+      chart: "/dev/null/some-chart",
+      namespace: "web",
+      values: { replicaCount: 2 },
+      capabilityProfile: { ...PROFILE },
+    }) as unknown as Parameters<typeof HelmRender>[0];
+
+  test("a pinned render persists by default, and an identical render is a store cache hit", () => {
+    HelmRender(pinnedProps());
+    expect(templateInvocations()).toBe(1);
+
+    const [record] = getHelmRenderRecords();
+    const manifest = loadRenderManifest(record.contentDigest!);
+    expect(manifest).toBeDefined();
+    expect(manifest!.inputDigest).toBe(record.inputDigest);
+    expect(manifest!.helmVersion).toBe("v4.1.1-fake");
+    expect(manifest!.releaseName).toBe("rel");
+    expect(loadRenderContent(record.contentDigest!)).toBeDefined();
+
+    // Second identical render: served from the store through the inputs
+    // index — helm template does not run again, and the recorded digests
+    // are unchanged.
+    clearHelmRenderRecords();
+    const result = HelmRender(pinnedProps());
+    expect(templateInvocations()).toBe(1);
+    const [second] = getHelmRenderRecords();
+    expect(second.contentDigest).toBe(record.contentDigest);
+    expect(second.inputDigest).toBe(record.inputDigest);
+    const keys = Object.keys(result.members as Record<string, unknown>);
+    expect(keys).toContain("ConfigMap_fake_render");
+    expect(keys).toContain("ServiceAccount_fake_sa");
+  });
+
+  test("persist: true on an unpinned render is a synth error naming the reason", () => {
+    expect(() =>
+      HelmRender({
+        name: "rel",
+        chart: "/dev/null/some-chart",
+        persist: true,
+      } as Parameters<typeof HelmRender>[0]),
+    ).toThrow(/unpinned.*no capabilityProfile declared/s);
+    // Refused before helm ran.
+    expect(templateInvocations()).toBe(0);
+  });
+
+  test("noCache renders fresh and skips the store; persist: true forces the write anyway", () => {
+    HelmRender({ ...pinnedProps(), noCache: true } as Parameters<typeof HelmRender>[0]);
+    expect(templateInvocations()).toBe(1);
+    expect(listRenderManifests({ root: storeRoot }).length).toBe(0);
+
+    HelmRender({ ...pinnedProps(), noCache: true, persist: true } as Parameters<typeof HelmRender>[0]);
+    expect(templateInvocations()).toBe(2);
+    expect(listRenderManifests({ root: storeRoot }).length).toBe(1);
+
+    // persist: false turns the store off even without noCache.
+    HelmRender({ ...pinnedProps(), name: "rel2", persist: false } as Parameters<typeof HelmRender>[0]);
+    expect(templateInvocations()).toBe(3);
+    expect(listRenderManifests({ root: storeRoot }).length).toBe(1);
+  });
+});