@intentius/chant-lexicon-helm 0.46.0 → 0.50.0

package/dist/render-wrapper.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Structure-preserving render wrapper (#1239, epic #1228 Phase 3).
+ *
+ * Turns a pinned render's document stream into chant-shaped routing groups
+ * WITHOUT restructuring the documents. Structure-preserving means the bytes
+ * that deploy are the bytes the render store recorded — this module only
+ * routes and labels; it never re-serializes, reorders lines, or edits a
+ * document. Each `RoutedDocument.text` is the exact document text from the
+ * input stream.
+ *
+ * Routing is by origin, not by kind. `helm template` stamps every document
+ * with `# Source: <chart>/<path>`, and the discriminator is whether that
+ * path contains a `crds/` **segment** (`(^|/)crds/` — `isCrdSource` from
+ * the #1234 classifier seeds):
+ *
+ * - A `crds/`-segment origin routes to the CRD group — the wrapper's
+ *   `crds/`. Segment matching is load-bearing: a subchart's CRDs arrive as
+ *   `charts/<child>/crds/<file>`, so a prefix rule catches none of them and
+ *   would route every subchart CRD into `templates/`, making it deletable
+ *   on uninstall (epic findings 4, 10 — the A/B test showed a flat wrap
+ *   converts `helm uninstall` from safe to data-destroying).
+ * - A hook-annotated template document (`helm.sh/hook` in
+ *   `metadata.annotations`) routes to its own group, annotations intact.
+ *   Hooks survive pinning (epic finding 5); they are surfaced separately so
+ *   the install path can account for them, never silently dropped.
+ * - Everything else routes to the main group — the wrapper's `templates/`.
+ *   A template-rendered `CustomResourceDefinition` stays here, because the
+ *   `crds/`-segment is the discriminator, not the kind: a chart that
+ *   templates its CRDs opted into template lifecycle semantics (upgrades
+ *   and deletes apply to them), and moving them to `crds/` would change
+ *   that. The routing notes it with a warning so the choice is visible.
+ *
+ * Aliased dependencies emit duplicate CRDs (epic finding 11): the same
+ * dependency included twice under an alias renders its `crds/` once per
+ * instance — two documents, one distinct CRD. The stored artifact keeps
+ * both (canonicalization is order- and duplicate-preserving), but a wrapper
+ * chart's `crds/` holds each CRD once, so the routed CRD group deduplicates
+ * by `(group, kind)`: the first occurrence wins and a warning names both
+ * sources. A CRD document that cannot be identified (unparseable, or
+ * missing `spec.group` / `spec.names.kind`) is never deduplicated — the
+ * routing must not silently drop what it cannot identify.
+ *
+ * The wrapper inherits the source chart's name and version (epic
+ * Decisions), keeping `helm history` continuous across the pinned
+ * migration; `RoutedRender.chart` / `chartVersion` carry them.
+ *
+ * This is the seam the pinned-install path (#1242) consumes:
+ * `routeStoredRender(contentDigest)` loads a stored render's canonical
+ * bytes and manifest and routes them.
+ */
+/** One routed document: exact bytes plus the labels routing derived from them. */
+export interface RoutedDocument {
+    /**
+     * The document's exact text from the input stream (from just past the
+     * `---` separator, trimmed of surrounding blank lines — the same split
+     * `splitDocuments` performs). Never re-serialized: what deploys is what
+     * was recorded.
+     */
+    text: string;
+    /**
+     * Chart-relative `# Source:` origin path (e.g. `crds/a.yaml`,
+     * `charts/kid/crds/kidcrd.yaml`), or `null` when the document carries no
+     * source header.
+     */
+    source: string | null;
+    /** Kubernetes kind, or `null` when the document does not parse to a kinded object. */
+    kind: string | null;
+    /** apiVersion as rendered, or `null`. */
+    apiVersion: string | null;
+    /** `metadata.name`, or `null`. */
+    name: string | null;
+}
+/** Machine-readable warning categories the routing emits. */
+export type RoutedRenderWarningCode = "duplicate-crd" | "template-crd";
+export interface RoutedRenderWarning {
+    /**
+     * - `duplicate-crd` — an aliased dependency emitted the same CRD twice;
+     *   the first occurrence was kept, the duplicate dropped. The message
+     *   names both sources.
+     * - `template-crd` — a `CustomResourceDefinition` was rendered from
+     *   `templates/` (no `crds/` segment in its origin). It stays in the main
+     *   group per the segment rule; this note makes the lifecycle choice
+     *   visible.
+     */
+    code: RoutedRenderWarningCode;
+    message: string;
+}
+/**
+ * A pinned render routed into the structure the wrapper chart preserves.
+ * The document groups partition the input stream (minus deduplicated CRD
+ * duplicates, each named in `warnings`); no document is ever silently
+ * dropped and no document text is ever altered.
+ */
+export interface RoutedRender {
+    /**
+     * Wrapper chart name — inherited from the source chart, so `helm history`
+     * stays continuous across the pinned migration (epic Decisions).
+     */
+    chart: string;
+    /** Wrapper chart version — inherited from the source chart; `null` for a local chart rendered without one. */
+    chartVersion: string | null;
+    /**
+     * Documents whose origin has a `crds/` segment — the wrapper's `crds/`,
+     * which is what keeps `helm uninstall` from deleting them (epic finding
+     * 4). Deduplicated by `(group, kind)`, first occurrence winning.
+     */
+    crds: RoutedDocument[];
+    /**
+     * Hook-annotated template documents (`helm.sh/hook`), annotations intact.
+     * Routed as their own group so the install path can account for them —
+     * never silently dropped (epic finding 5).
+     */
+    hooks: RoutedDocument[];
+    /** Everything else — the wrapper's `templates/`. */
+    main: RoutedDocument[];
+    /** What routing had to decide beyond the mechanical rule: dropped duplicates, template-rendered CRDs. */
+    warnings: RoutedRenderWarning[];
+}
+export interface RouteRenderOptions {
+    /** Source chart name — becomes the wrapper's name. */
+    chart: string;
+    /** Source chart version — becomes the wrapper's version. */
+    chartVersion?: string | null;
+}
+/**
+ * Route a rendered stream (canonical or raw `helm template` output) into
+ * `RoutedRender` groups. Pure over the stream: no store access, no helm.
+ */
+export declare function routeRender(rendered: string, opts: RouteRenderOptions): RoutedRender;
+/**
+ * Route a stored pinned render by its `contentDigest`: loads the canonical
+ * bytes and the `RenderManifest` from the render store (#1238) and routes
+ * them, inheriting the manifest's chart name and version. This is the seam
+ * the pinned-install path (#1242) consumes. `undefined` when the store has
+ * no such entry.
+ */
+export declare function routeStoredRender(contentDigest: string, opts?: {
+    root?: string;
+}): RoutedRender | undefined;
+//# sourceMappingURL=render-wrapper.d.ts.map

package/dist/render-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-wrapper.d.ts","sourceRoot":"","sources":["../src/render-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AASH,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,sFAAsF;IACtF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,yCAAyC;IACzC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,kCAAkC;IAClC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,6DAA6D;AAC7D,MAAM,MAAM,uBAAuB,GAAG,eAAe,GAAG,cAAc,CAAC;AAEvE,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;OAQG;IACH,IAAI,EAAE,uBAAuB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,8GAA8G;IAC9G,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;OAIG;IACH,IAAI,EAAE,cAAc,EAAE,CAAC;IACvB;;;;OAIG;IACH,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,oDAAoD;IACpD,IAAI,EAAE,cAAc,EAAE,CAAC;IACvB,yGAAyG;IACzG,QAAQ,EAAE,mBAAmB,EAAE,CAAC;CACjC;AA0DD,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,YAAY,CA0DpF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACvB,YAAY,GAAG,SAAS,CAM1B"}

package/dist/render.d.ts

@@ -30,6 +30,7 @@
  *   values: { installCRDs: true },
  * });
  */
+import { type HelmCapabilityProfile, type HelmCapabilityProfileRef } from "./config.js";
 export interface HelmRenderProps {
     /** Logical name for the render (used in cache key + composite name). */
     name: string;
@@ -50,6 +51,86 @@ 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;
 }
+/** Every render recorded in this process, in invocation order. */
+export declare function getHelmRenderRecords(): readonly HelmRenderRecord[];
+/** Reset the record list (test isolation). */
+export declare function clearHelmRenderRecords(): void;
 export declare const HelmRender: import("@intentius/chant").CompositeDefinition<HelmRenderProps, import("@intentius/chant").CompositeMembers>;
 //# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAeH,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAuHD,eAAO,MAAM,UAAU,8GA8BP,CAAC"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAeH,OAAO,EAA4B,KAAK,qBAAqB,EAAE,KAAK,wBAAwB,EAAE,MAAM,UAAU,CAAC;AAU/G,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;IAC7C;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4GAA4G;IAC5G,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IAC1C,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oGAAoG;IACpG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAID,kEAAkE;AAClE,wBAAgB,oBAAoB,IAAI,SAAS,gBAAgB,EAAE,CAElE;AAED,8CAA8C;AAC9C,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAmRD,eAAO,MAAM,UAAU,8GAsFP,CAAC"}

package/dist/rules/whm503.ts

@@ -0,0 +1,101 @@
+/**
+ * WHM503: Pinned render artifact carries Secret data.
+ *
+ * WHM407 covers the pre-render concern — a chart TEMPLATE with an inline,
+ * literal `data`/`stringData` value baked into `templates/`. This rule
+ * covers a different concern (#1241, epic #1228 Phase 3): the STORED,
+ * POST-RENDER artifact (`render-store.ts`, #1238). A pinned render is
+ * durable, promoted, and pushed to a registry — unlike a normal `helm
+ * upgrade`, whose rendered bytes are computed at deploy time and discarded.
+ * By the time a render lands in the store, every `.Values` reference and
+ * `{{ }}` expression is resolved, so a `kind: Secret` document with
+ * populated `data`/`stringData` there is a live credential baked into
+ * something that outlives the deploy that produced it.
+ *
+ * Scans every pinned render recorded so far in this process
+ * (`getHelmRenderRecords()` from `../../render`) that carries a
+ * `contentDigest`, loads its manifest + canonical content from the render
+ * store, and flags any `Secret` document whose `data` or `stringData` is
+ * non-empty.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import yaml from "js-yaml";
+
+import type { HelmRenderRecord } from "../../render";
+import { getHelmRenderRecords } from "../../render";
+import { loadRenderManifest, readRenderDocument } from "../../render-store";
+
+interface ParsedSecretDoc {
+  data?: unknown;
+  stringData?: unknown;
+}
+
+/** True when a `data`/`stringData` map carries at least one key. */
+function isPopulated(value: unknown): boolean {
+  return typeof value === "object" && value !== null && Object.keys(value).length > 0;
+}
+
+/**
+ * Scan a set of `HelmRenderRecord`s for pinned renders whose stored artifact
+ * carries a `Secret` document with populated `data`/`stringData`. Exported
+ * separately from `whm503` so tests can drive it directly with hand-built
+ * records — no real `helm` binary required, unlike a `HelmRender()` call.
+ * `opts.root` overrides the render store root (test isolation).
+ */
+export function checkRenderRecordsForSecrets(
+  records: readonly HelmRenderRecord[],
+  opts?: { root?: string },
+): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const record of records) {
+    if (!record.contentDigest) continue; // unpinned — no stored artifact to scan
+
+    const manifest = loadRenderManifest(record.contentDigest, opts);
+    if (!manifest) continue; // recorded but not (or no longer) in the store
+
+    for (const doc of manifest.documents) {
+      if (doc.kind !== "Secret") continue;
+
+      const found = readRenderDocument(record.contentDigest, { kind: doc.kind, name: doc.name, namespace: doc.namespace }, opts);
+      if (!found) continue;
+
+      let parsed: ParsedSecretDoc;
+      try {
+        parsed = (yaml.load(found.text) ?? {}) as ParsedSecretDoc;
+      } catch {
+        continue; // unparseable — not this check's problem to diagnose
+      }
+
+      if (!isPopulated(parsed.data) && !isPopulated(parsed.stringData)) continue;
+
+      const locator = doc.namespace ? `${doc.namespace}/${doc.name}` : doc.name;
+      diagnostics.push({
+        checkId: "WHM503",
+        severity: "error",
+        message:
+          `pinned render "${record.name}" (${record.chart}, ${record.contentDigest}): Secret "${locator}" ` +
+          `carries populated data/stringData — a pinned render is stored, promoted, and pushed to a registry, ` +
+          `so this bakes a live credential into a durable artifact. Declare the value with runtimeSlot() so ` +
+          `it is supplied per environment, or replace this Secret with HelmExternalSecret.`,
+        entity: locator,
+        lexicon: "helm",
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+export const whm503: PostSynthCheck = {
+  id: "WHM503",
+  description: "Pinned render artifact must not carry populated Secret data/stringData",
+
+  // This check's data source is the render store (#1238), not `ctx.outputs`
+  // (the un-rendered chart template files WHM005-WHM502 read) — see the file
+  // doc comment. `ctx` is accepted to satisfy `PostSynthCheck` and is unused.
+  check(_ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkRenderRecordsForSecrets(getHelmRenderRecords());
+  },
+};

package/dist/rules/whm504.ts

@@ -0,0 +1,52 @@
+/**
+ * WHM504: Dead value assignment (#1252, epic #1228 Phase 7).
+ *
+ * A supplied value that never survives coalescing is a lie in the config:
+ * it reads as if it configures something, and nothing ever sees it. The
+ * coalesced-values probe (#1251, ../../values-probe.ts) knows three ways a
+ * supplied value dies — shadowed by a later supplied layer, targeting a
+ * dependency a `condition:` disabled, or a values map under a top-level key
+ * that names no dependency at all (the silently-ignored subchart typo).
+ *
+ * The check reports over the probe records of the current process
+ * (`getValuesProbeRecords`): whatever ran the probe — the pinned-render
+ * build path, a test, a direct call — this check turns its dead assignments
+ * into diagnostics. No probe run, nothing to report; the probe itself needs
+ * the helm binary and the chart source, which a post-synth check must not
+ * require on its own.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getValuesProbeRecords, type DeadAssignment } from "../../values-probe";
+
+function describe(dead: DeadAssignment): string {
+  switch (dead.reason) {
+    case "shadowed":
+      return `supplied value "${dead.path}" (${dead.origin}) never survives coalescing — shadowed by ${dead.shadowedBy}`;
+    case "disabled-subchart":
+      return `supplied value "${dead.path}" (${dead.origin}) targets a disabled subchart — ${dead.shadowedBy}`;
+    case "unknown-subchart":
+      return `supplied values under "${dead.path}" (${dead.origin}) target no subchart — ${dead.shadowedBy}`;
+  }
+}
+
+export const whm504: PostSynthCheck = {
+  id: "WHM504",
+  description: "Detect supplied values that never survive coalescing (shadowed, disabled subchart, unknown subchart)",
+
+  check(_ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const record of getValuesProbeRecords()) {
+      for (const dead of record.probe.deadAssignments) {
+        diagnostics.push({
+          checkId: "WHM504",
+          severity: "warning",
+          message: describe(dead),
+          entity: record.name,
+          lexicon: "helm",
+        });
+      }
+    }
+    return diagnostics;
+  },
+};

package/dist/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
 

package/dist/values-probe.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Build-time coalesced-values probe (#1251, epic #1228 Phase 7) and the
+ * provenance derived from it (#1252).
+ *
+ * `helm template --debug` does not print coalesced values on either major
+ * version, and `helm get values --all` needs an installed release — the
+ * wrong side of the build/deploy line. So the probe extracts them from helm
+ * itself: copy the chart, replace every (sub)chart's `templates/` with a
+ * single `chant-values-probe.yaml` template containing `{{ toYaml .Values }}`,
+ * render, lift the probe documents out, discard the copy. Coalescing —
+ * parent-overrides-child, `global` propagation, alias scoping,
+ * `import-values`, tags — is delegated to helm rather than reimplemented
+ * (the approximation in `pinnability/values.ts` remains only as the
+ * classifier's offline fallback).
+ *
+ * The probe filename must NOT begin with `_`: helm treats underscore-prefixed
+ * template files as partials and skips them without error.
+ *
+ * The probe runs against a private copy in a temp directory, so the probe
+ * document can never appear in a real render of the chart — the pinned
+ * artifact path (#1237/#1242) never sees the injected template.
+ *
+ * A dependency disabled by a `condition:` (or tags) is pruned by helm before
+ * rendering, so it yields no probe document. Those instances are reported in
+ * `disabled` instead, with the condition path where determinable. Note the
+ * ROOT probe document still carries the values subtree a disabled dependency
+ * would have received — an installed release omits it (epic findings 14, 15).
+ *
+ * On the probe output, three provenance products (#1252):
+ *
+ * - `digest` — `sha256:` over the canonical JSON (core's `canonicalJson`,
+ *   the #1237 convention) of the per-instance coalesced trees, keyed by
+ *   scope path. Same inputs, same coalesced values, same digest.
+ * - `valueSources` — each coalesced path attributed to its winning layer:
+ *   chart default / parent override / supplied file / --set.
+ * - `deadAssignments` — supplied values that never survive coalescing:
+ *   shadowed by a later supplied layer, or targeting a disabled or unknown
+ *   subchart path. WHM504 turns these into lint diagnostics.
+ */
+/** Where a coalesced value came from. `computed` = no supplied or authored layer matches (e.g. `import-values`). */
+export type ValueOrigin = "chart default" | "parent override" | "supplied file" | "--set" | "computed";
+/**
+ * One layer of values supplied to the render, in ascending precedence order
+ * (a later layer overrides an earlier one, like repeated `--values` flags;
+ * `--set` layers conventionally come last). `origin` is the label reported
+ * by `valueSources` and dead-assignment findings.
+ */
+export interface SuppliedValuesLayer {
+    origin: "supplied file" | "--set";
+    /** Optional identifier (a file path, a flag) used in messages. */
+    name?: string;
+    values: Record<string, unknown>;
+}
+/** One chart instance and the values helm coalesced for it. */
+export interface CoalescedChartValues {
+    /** Value scope from the root: `[]` for the root chart, `["kidtwo"]` for an aliased dependency, nested for grandchildren. */
+    scope: string[];
+    /** `.Chart.Name` as rendered — the alias for an aliased dependency. */
+    chartName: string;
+    /** The fully coalesced values this instance saw, exactly as helm computed them. */
+    values: Record<string, unknown>;
+}
+/** A declared dependency helm pruned before rendering. */
+export interface DisabledDependency {
+    scope: string[];
+    /** The dependency's real chart name (not the alias). */
+    name: string;
+    /** The `condition:` path that resolved false, when determinable (tags-disabled dependencies carry none). */
+    condition?: string;
+}
+/** A supplied value that never survives coalescing. */
+export interface DeadAssignment {
+    /** Dot-joined path in root coordinates. */
+    path: string;
+    /** The layer that supplied it, e.g. `supplied file (values-prod.yaml)`. */
+    origin: string;
+    reason: "shadowed" | "disabled-subchart" | "unknown-subchart";
+    /** What killed it: the shadowing layer, or the disabling condition. */
+    shadowedBy?: string;
+}
+export interface CoalescedValuesProbe {
+    /** Enabled chart instances, root first, then by scope path. */
+    instances: CoalescedChartValues[];
+    disabled: DisabledDependency[];
+    /** `sha256:` over the canonical JSON of the per-instance coalesced trees. */
+    digest: string;
+    /** Dot-joined path (root coordinates, subchart paths scope-prefixed) to winning layer. */
+    valueSources: Record<string, ValueOrigin>;
+    deadAssignments: DeadAssignment[];
+    warnings: string[];
+}
+export interface ValuesProbeOptions {
+    /** Directory of the chart to probe (must contain Chart.yaml). Never modified — the probe works on a copy. */
+    chartDir: string;
+    /** Logical name recorded with the probe. Defaults to the release name. */
+    name?: string;
+    /** Release name passed to `helm template`. Default `chant-values-probe`. */
+    releaseName?: string;
+    namespace?: string;
+    /** Values layers in ascending precedence order. */
+    supplied?: SuppliedValuesLayer[];
+    /** Injectable helm runner (tests). Receives the full argv after `helm`. */
+    runHelm?: (args: string[]) => string;
+}
+/**
+ * The coalesced-values identity: `sha256:` over the canonical JSON of the
+ * per-instance trees keyed by scope path — the #1237 digest conventions
+ * (core `canonicalJson`, `sha256:` prefix). Two renders that coalesce the
+ * same values for every instance share it; any value, in any subchart,
+ * changing breaks it.
+ */
+export declare function coalescedValuesDigest(instances: readonly CoalescedChartValues[]): string;
+/** Inputs the pure provenance analysis needs — separable from the render for tests. */
+export interface ValuesAttributionInput {
+    instances: readonly CoalescedChartValues[];
+    supplied: readonly SuppliedValuesLayer[];
+    /** The chart-default `values.yaml` for an instance scope; undefined when unknown. */
+    defaultsFor: (scope: readonly string[]) => Record<string, unknown> | undefined;
+}
+/**
+ * Attribute each coalesced path to the layer that won it.
+ *
+ * Keys are dot-joined root-coordinate paths: a subchart instance's paths are
+ * prefixed with its scope, so `kidtwo.replicas` is the `replicas` the
+ * `kidtwo` instance actually sees. A key of an instance's tree that is
+ * itself an enabled child scope is skipped — helm pushes the child's
+ * coalesced tree back into the parent's `.Values`, and the child instance
+ * owns those paths.
+ *
+ * Layer precedence mirrors helm: supplied layers (last first), then ancestor
+ * chart defaults (root outranks intermediates — "parent override"), then the
+ * instance's own defaults ("chart default"). A path no layer explains — an
+ * `import-values` product, a helm-computed merge — reports `computed`.
+ * Attribution matches on value equality, so a layer that assigned a path but
+ * lost it reports as the layer that actually won.
+ */
+export declare function computeValueSources(input: ValuesAttributionInput): Record<string, ValueOrigin>;
+/**
+ * Supplied values that never survive coalescing:
+ *
+ * - `shadowed` — a later supplied layer assigns the same path (a map merging
+ *   into a map is not a shadow; anything else replaces).
+ * - `disabled-subchart` — the path targets a dependency a `condition:` (or
+ *   tags) disabled, so no rendered chart ever reads it.
+ * - `unknown-subchart` — a map supplied under a top-level key that matches
+ *   no dependency, no root default, and not `global`, on a chart that HAS
+ *   dependencies: the classic silently-ignored typo of a subchart name.
+ *   Reported once per top-level key per layer.
+ */
+export declare function findDeadAssignments(input: ValuesAttributionInput, disabled: readonly DisabledDependency[]): DeadAssignment[];
+/**
+ * Run the probe: copy the chart, inject probe templates, render, lift the
+ * probe documents out, analyze, discard the copy. The source chart is never
+ * touched. Every run is recorded for WHM504 (`getValuesProbeRecords`).
+ */
+export declare function probeCoalescedValues(options: ValuesProbeOptions): CoalescedValuesProbe;
+/** What one probe run recorded about itself — the WHM504 lint surface. */
+export interface HelmValuesProbeRecord {
+    name: string;
+    chartDir: string;
+    probe: CoalescedValuesProbe;
+}
+/** Every probe recorded in this process, in invocation order. */
+export declare function getValuesProbeRecords(): readonly HelmValuesProbeRecord[];
+/** Record a probe computed elsewhere (the render path integration point). */
+export declare function recordValuesProbe(record: HelmValuesProbeRecord): void;
+/** Reset the record list (test isolation). */
+export declare function clearValuesProbeRecords(): void;
+/**
+ * The values gap between the probe and an installed release: an installed
+ * release's `helm get values --all` omits subtrees for disabled
+ * dependencies; the probe's root document keeps them (epic findings 14, 15).
+ * On shared keys the two agree — this helper names the shared-key view for
+ * comparisons against a live release.
+ */
+export declare function rootCoalescedValues(probe: CoalescedValuesProbe): Record<string, unknown>;
+//# sourceMappingURL=values-probe.d.ts.map

package/dist/values-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"values-probe.d.ts","sourceRoot":"","sources":["../src/values-probe.ts"],"names":[],"mappings":"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"}

package/dist/wrapper-chart.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Wrapper-chart materialization for the pinned install path (#1242, epic
+ * #1228 Phase 4).
+ *
+ * Turns a `RoutedRender` (#1239) into an installable helm chart on disk.
+ * The wrapper preserves the recorded bytes exactly:
+ *
+ * - CRD-group documents are written verbatim into the wrapper's `crds/`,
+ *   which is what keeps `helm uninstall` from deleting them — the A/B test
+ *   behind epic finding 4 showed a flat wrap converts uninstall from safe
+ *   to data-destroying.
+ * - Every other document (main and hook groups) is written verbatim into
+ *   `manifests/`, and each gets a one-line shim in `templates/` that reads
+ *   it back with `.Files.Get`. The shim exists because rendered output can
+ *   legitimately contain template-looking text — a ConfigMap carrying
+ *   alertmanager notification templates renders `{{ $labels }}` as literal
+ *   bytes — and a document placed directly in `templates/` would be run
+ *   through the template engine a second time, mangling or failing on
+ *   exactly those bytes. `.Files.Get` returns file content untemplated, so
+ *   what helm installs is what the render store recorded.
+ * - Hook documents go through the same shim; their `helm.sh/hook`
+ *   annotations are part of the recorded bytes, so helm registers and runs
+ *   them from the rendered output unchanged (epic finding 5).
+ *
+ * The wrapper inherits the source chart's name and version (epic
+ * Decisions), keeping `helm history` continuous across the pinned
+ * migration. A local chart path becomes its sanitized basename — helm
+ * requires a bare chart name — and a render recorded without a version
+ * falls back to `0.0.0`.
+ */
+import type { RoutedRender } from "./render-wrapper.js";
+/** What `materializeWrapperChart` wrote, with the counts the install result reports. */
+export interface MaterializedWrapperChart {
+    /** Chart root directory — the `helm upgrade --install` argument. */
+    dir: string;
+    /** Wrapper chart name (sanitized from the source chart reference). */
+    chartName: string;
+    /** Wrapper chart version (`0.0.0` when the render recorded none). */
+    chartVersion: string;
+    /** Files written under `crds/`, chart-relative. */
+    crdFiles: string[];
+    /** Verbatim document files written under `manifests/`, chart-relative, in emit order. */
+    manifestFiles: string[];
+    /** Number of hook documents among `manifestFiles`. */
+    hookCount: number;
+}
+/**
+ * A valid helm chart name from a chart reference that may be a local path
+ * (`./charts/web`) or a repo-qualified name. Takes the last path segment,
+ * lowercases it, and collapses anything outside `[a-z0-9-]` to `-` — helm
+ * chart names are DNS-label-shaped. Falls back to `pinned-chart` when
+ * nothing survives.
+ */
+export declare function wrapperChartName(chart: string): string;
+/**
+ * Write `routed` as an installable wrapper chart under `dir` (which must
+ * exist and should be empty). Document text is written byte-for-byte; the
+ * only authored files are `Chart.yaml` and the `.Files.Get` shims.
+ */
+export declare function materializeWrapperChart(routed: RoutedRender, dir: string): MaterializedWrapperChart;
+//# sourceMappingURL=wrapper-chart.d.ts.map