@intentius/chant-lexicon-helm 0.46.0 → 0.50.0

package/dist/okf/index.md

@@ -37,3 +37,5 @@ okf_version: '0.2'
 * [WHM407](/rules/WHM407.md) - Secrets with inline data should use ExternalSecret or SealedSecret
 * [WHM501](/rules/WHM501.md) - Detect values keys that are defined but never referenced in templates
 * [WHM502](/rules/WHM502.md) - Detect deprecated or invalid Kubernetes API versions
+* [WHM503](/rules/WHM503.md) - Pinned render artifact must not carry populated Secret data/stringData
+* [WHM504](/rules/WHM504.md) - Detect supplied values that never survive coalescing (shadowed, disabled subchart, unknown subchart)

package/dist/okf/rules/WHM503.md

@@ -0,0 +1,15 @@
+---
+type: post-synth-check
+title: WHM503
+description: Pinned render artifact must not carry populated Secret data/stringData
+id: WHM503
+severity: error
+category: post-synth
+lexicon: helm
+docs: https://intentius.io/chant/lexicons/helm/rules/
+---
+Pinned render artifact must not carry populated Secret data/stringData
+
+## Applies to
+
+- [Values](/types/Values.md)

package/dist/okf/rules/WHM504.md

@@ -0,0 +1,11 @@
+---
+type: post-synth-check
+title: WHM504
+description: Detect supplied values that never survive coalescing (shadowed, disabled subchart, unknown subchart)
+id: WHM504
+severity: error
+category: post-synth
+lexicon: helm
+docs: https://intentius.io/chant/lexicons/helm/rules/
+---
+Detect supplied values that never survive coalescing (shadowed, disabled subchart, unknown subchart)

package/dist/okf/types/Values.md

@@ -22,3 +22,4 @@ Typed values definition — emits values.yaml and values.schema.json.
 - [WHM405](/rules/WHM405.md): Resource specs should include cpu and memory in limits/requests
 - [WHM407](/rules/WHM407.md): Secrets with inline data should use ExternalSecret or SealedSecret
 - [WHM501](/rules/WHM501.md): Detect values keys that are defined but never referenced in templates
+- [WHM503](/rules/WHM503.md): Pinned render artifact must not carry populated Secret data/stringData

package/dist/op/activities/cluster-probe.d.ts

@@ -0,0 +1,44 @@
+/** What the probe read off the live cluster. */
+export interface LiveClusterCapabilities {
+    /** The server's full version string (`serverVersion.gitVersion`), e.g. `v1.33.6+k3s1`. */
+    kubeVersion: string;
+    /** The server's `major.minor`, e.g. `1.33`, parsed from `serverVersion.major`/`minor` (or `gitVersion` when those are absent). */
+    majorMinor: string;
+    /** Every API version the cluster serves, one `group/version` (or `v1`) per entry, from `kubectl api-versions`. */
+    apiVersions: string[];
+}
+/**
+ * Thrown when the cluster's capabilities cannot be read at all — kubectl
+ * missing, cluster unreachable, or unparseable output. A deploy that
+ * declared a profile cannot verify its guarantee through this error, so the
+ * caller must refuse to proceed rather than deploy blind.
+ */
+export declare class ClusterProbeError extends Error {
+    constructor(message: string);
+}
+/** `major.minor` from a declared or live version string (`1.33`, `1.33.6`, `v1.33.6+k3s1`). Undefined when the string has no parseable major.minor. */
+export declare function majorMinorOf(version: string): string | undefined;
+/**
+ * Read the target cluster's capabilities. Uses whatever kubeconfig/context
+ * the process environment provides — the same ambient target `helm upgrade`
+ * itself will act on, so the probe and the deploy see one cluster.
+ */
+export declare function probeClusterCapabilities(signal?: AbortSignal): Promise<LiveClusterCapabilities>;
+/** The declared facts a profile asserts about a cluster — the activity-side profile shape. */
+export interface DeclaredCapabilityProfile {
+    name?: string;
+    kubeVersion?: string;
+    apiVersions?: string[];
+}
+/**
+ * Every way `live` diverges from what `profile` declares, one message per
+ * divergence, each naming the declared and the live value. Empty when the
+ * cluster matches the profile.
+ *
+ * kubeVersion compares on major.minor (see module doc). apiVersions is a
+ * subset check: everything the profile declares must be served; extra API
+ * versions on the cluster are not a divergence, since a render only ever
+ * probed the declared set.
+ */
+export declare function compareCapabilityProfile(profile: DeclaredCapabilityProfile, live: LiveClusterCapabilities): string[];
+//# sourceMappingURL=cluster-probe.d.ts.map

package/dist/op/activities/cluster-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-probe.d.ts","sourceRoot":"","sources":["../../../src/op/activities/cluster-probe.ts"],"names":[],"mappings":"AAyBA,gDAAgD;AAChD,MAAM,WAAW,uBAAuB;IACtC,0FAA0F;IAC1F,WAAW,EAAE,MAAM,CAAC;IACpB,kIAAkI;IAClI,UAAU,EAAE,MAAM,CAAC;IACnB,kHAAkH;IAClH,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,uJAAuJ;AACvJ,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGhE;AA6BD;;;;GAIG;AACH,wBAAsB,wBAAwB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAqBrG;AAED,8FAA8F;AAC9F,MAAM,WAAW,yBAAyB;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,yBAAyB,EAClC,IAAI,EAAE,uBAAuB,GAC5B,MAAM,EAAE,CAkBV"}

package/dist/op/activities/helm.d.ts

@@ -1,18 +1,192 @@
+import { type AutoReleaseResult } from "@intentius/chant/components/auto-release";
+/**
+ * The cluster capability profile a deploy is declared against (epic #1228).
+ * Declared, never sniffed — the epic's finding 1 shows the default kube
+ * version is a property of the helm binary, so an undeclared profile cannot
+ * be part of a stable identity. When declared it joins the input digest.
+ */
+export interface HelmCapabilityProfile {
+    /** The profile's declared name (its `helm.capabilityProfiles` key), used in assertion messages. Not part of the digest — only the declared facts are. */
+    name?: string;
+    /** Kubernetes version the render targets (`--kube-version`). */
+    kubeVersion?: string;
+    /** Extra API versions the render assumes (`--api-versions`). Order-insensitive for the digest. */
+    apiVersions?: string[];
+}
 export interface HelmInstallArgs {
     /** Helm release name. */
     name: string;
-    /** Chart reference (local path or `repo/chart`). */
-    chart: string;
+    /**
+     * Chart reference (local path or `repo/chart`). Required for an unpinned
+     * deploy; refused alongside `contentDigest` — a pinned deploy's bytes come
+     * from the render store, never from a deploy-time render.
+     */
+    chart?: string;
+    /**
+     * `sha256:` content digest of a stored pinned render (#1242). When set,
+     * the deploy takes the pinned path: the recorded render is loaded from the
+     * render store, its digest verified, and those exact bytes installed as a
+     * structure-preserving wrapper chart — no deploy-time render. The chart /
+     * values / set / chartVersion render inputs are refused in this mode.
+     */
+    contentDigest?: string;
+    /** Render store root override for the pinned path (tests, non-default stores). Defaults to `CHANT_HELM_RENDER_ROOT` / `~/.chant/helm-renders`. */
+    renderStoreRoot?: string;
+    /** Chart version to pin (`--version`). Part of the input digest. */
+    chartVersion?: string;
     /** Path to a values file. */
     values?: string;
-    /** Kubernetes namespace. */
+    /** Kubernetes namespace. Defaults to the stored render's namespace on the pinned path. */
     namespace?: string;
     /** Additional --set arguments. */
     set?: Record<string, string>;
+    /** Capability profile the deploy is declared against, if any. Part of the input digest when declared, and asserted against the live target cluster before any helm mutation (#1244). */
+    capabilityProfile?: HelmCapabilityProfile;
+    /**
+     * Deliberate escape hatch for the capability-profile assertion (#1244).
+     * When the live cluster diverges from the declared profile — or cannot be
+     * probed at all — the deploy normally refuses before any helm mutation.
+     * Set `true` to deploy anyway; the bypassed divergences are warned about
+     * and recorded in the release record (`profileOverride`), so the ledger
+     * shows the release knowingly skewed from its declared profile. Has no
+     * effect when the cluster matches, and none when no profile is declared.
+     */
+    overrideProfileAssertion?: boolean;
+    /** Component name for the release record. Defaults to the release `name` — a chart's release is its deploy unit. */
+    component?: string;
+    /** Environment for the release record. Defaults to `"local"`, the same default `chant run --components` applies. */
+    env?: string;
+    /** Run id for the release record. Defaults to `$GITHUB_RUN_ID`/`$CI_PIPELINE_ID`, then a locally generated id — the same fallback chain `chant components release` uses. */
+    runId?: string;
+    /** Set `false` to skip release-record emission, mirroring `--no-release-record`. Default: emission is ON. */
+    recordRelease?: boolean;
+}
+/** What `helmInstall` returns: the input digest and the release-record outcome, so a workflow can carry both. */
+export interface HelmInstallResult {
+    /**
+     * `sha256:` digest over the deploy's *inputs* — chart, chart version,
+     * resolved values, capability profile if declared (#1243). This is the
+     * input-side join key: two environments deploying the same chart at the
+     * same version with the same values share it even when their clusters
+     * legitimately differ. It is deliberately not a rendered-output digest —
+     * that is the pinned-render work of later #1228 phases. Absent only when
+     * the digest could not be computed (see `release.reason`).
+     */
+    inputDigest?: string;
+    /** Outcome of the ledger append — `recorded: true` carries the `ReleaseRecord` written. */
+    release: AutoReleaseResult;
+    /**
+     * Outcome of the deploy-time capability-profile assertion (#1244). Present
+     * exactly when the deploy declared a profile with assertable facts (on the
+     * pinned path the stored render's profile always is one). A mismatch
+     * without the override never reaches a result — the activity throws before
+     * any helm mutation — so a present outcome is either a verified match or a
+     * deliberate, recorded override.
+     */
+    profileAssertion?: HelmProfileAssertionOutcome;
+    /** Helm release name the deploy targeted (`args.name`). */
+    releaseName: string;
+    /** Namespace the deploy targeted, or `null` when helm's default applied. */
+    namespace: string | null;
+    /**
+     * True when this deploy took the pinned path (#1242): recorded bytes
+     * loaded from the render store, digest-verified, installed as a wrapper
+     * chart with no deploy-time render.
+     */
+    pinned: boolean;
+    /**
+     * `sha256:` content digest of the installed render — the artifact identity
+     * (the epic's `renderDigest`, named for the #1237 split). Pinned path only:
+     * an unpinned deploy has no rendered-output identity to report.
+     */
+    contentDigest?: string;
+    /**
+     * Release revision after the deploy, from `helm get metadata -o json`.
+     * Pinned path only, and absent when the metadata read failed after a
+     * successful install (best-effort, like the ledger append).
+     */
+    revision?: number;
+    /** Chart version installed — `helm get metadata`'s `version`, falling back to the stored render's. Pinned path only. */
+    chartVersion?: string | null;
+    /** Number of CRD documents shipped in the wrapper's `crds/` (uninstall-safe; epic finding 4). Pinned path only. */
+    crdsApplied?: number;
+    /** Number of non-CRD documents installed through the wrapper's templates (hook documents included). Pinned path only. */
+    docsApplied?: number;
+    /** Number of hook documents among `docsApplied` — helm registers and runs them from their recorded annotations (epic finding 5). Pinned path only. */
+    hooksRun?: number;
 }
+/** Thrown by the pinned path (#1242) when `contentDigest` resolves to nothing in the render store. */
+export declare class PinnedRenderNotFoundError extends Error {
+    constructor(contentDigest: string, root: string);
+}
+/** Thrown by the pinned path (#1242) when the stored bytes no longer hash to their digest — store corruption, caught before any mutation. */
+export declare class PinnedRenderIntegrityError extends Error {
+    constructor(contentDigest: string, actual: string);
+}
+/** Thrown by the pinned path (#1242) when the call mixes pinned and unpinned inputs, or targets a release name the bytes were not rendered for. */
+export declare class PinnedInstallInputError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown by the pinned path (#1242) when the deploy's declared capability
+ * profile disagrees with the profile recorded in the stored render's
+ * manifest. Distinct from `CapabilityProfileMismatchError` (#1244, declared
+ * vs *live cluster*): this is declared vs *recorded*, checked first and
+ * entirely offline.
+ */
+export declare class PinnedProfileMismatchError extends Error {
+    constructor(release: string, contentDigest: string, divergences: string[]);
+}
+/** How the deploy-time profile assertion (#1244) concluded, when a profile was declared. */
+export type HelmProfileAssertionOutcome = {
+    matched: true;
+} | {
+    matched: false;
+    divergences: string[];
+    overridden: true;
+};
+/**
+ * Thrown before any helm mutation when the target cluster does not match the
+ * deploy's declared capability profile (#1244). The message names every
+ * divergence — declared vs live — so the refusal is specific, never a shrug.
+ */
+export declare class CapabilityProfileMismatchError extends Error {
+    readonly divergences: string[];
+    constructor(release: string, profileName: string | undefined, divergences: string[]);
+}
+/**
+ * The input-side identity of a helm deploy (#1243): a `sha256:` digest over
+ * the canonical JSON of `{ chart, chartVersion, values, capabilityProfile? }`.
+ * Canonical JSON (core's `canonicalJson`, RFC 8785 shape) sorts object keys,
+ * so the digest is stable across value key order; `apiVersions` is sorted
+ * for the same reason. The digest changes when any actual input changes —
+ * the chart, its version, a value, the declared profile.
+ *
+ * Delegates to `helmInputDigest` (#1237) — the same helper `HelmRender`
+ * records as a pinned render's `inputDigest` — so a deploy and a render of
+ * the same inputs share their identity by construction.
+ */
+export declare function helmInstallInputDigest(args: HelmInstallArgs): string;
 /**
- * Run `helm upgrade --install <name> <chart>`.
+ * Deploy a helm release and append a `ReleaseRecord` (#1243).
+ *
+ * Two paths, selected by `contentDigest`:
+ *
+ * - **Unpinned** (no `contentDigest`): `helm upgrade --install <name>
+ *   <chart>`, exactly as before #1242 — helm renders at deploy time. The
+ *   ledger record is keyed by the input digest.
+ * - **Pinned** (`contentDigest` set, #1242): the recorded render is loaded
+ *   from the render store, its digest verified, and those exact bytes
+ *   installed as a structure-preserving wrapper chart — no deploy-time
+ *   render. The ledger record is keyed by the content digest and carries
+ *   the stored render's input digest alongside it.
+ *
+ * A ledger-append failure after a successful deploy warns and never throws:
+ * the deploy already happened, so a ledger-write hiccup must not turn a
+ * finished deploy into a failed activity — the record is observability, not
+ * part of the deploy itself.
+ *
  * Uses longInfra profile — 20m timeout, heartbeat every 15s.
  */
-export declare function helmInstall(args: HelmInstallArgs, signal?: AbortSignal): Promise<void>;
+export declare function helmInstall(args: HelmInstallArgs, signal?: AbortSignal): Promise<HelmInstallResult>;
 //# sourceMappingURL=helm.d.ts.map

package/dist/op/activities/helm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helm.d.ts","sourceRoot":"","sources":["../../../src/op/activities/helm.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,eAAe;IAC9B,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB5F"}
+{"version":3,"file":"helm.d.ts","sourceRoot":"","sources":["../../../src/op/activities/helm.ts"],"names":[],"mappings":"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"}

package/dist/op/activities/index.d.ts

@@ -6,6 +6,8 @@
  * The `helmInstall` step builder stays in core (@intentius/chant/op), re-exported
  * from the temporal Op-authoring barrel like the other core builders.
  */
-export { helmInstall } from "./helm.js";
-export type { HelmInstallArgs } from "./helm.js";
+export { helmInstall, helmInstallInputDigest, CapabilityProfileMismatchError, PinnedRenderNotFoundError, PinnedRenderIntegrityError, PinnedInstallInputError, PinnedProfileMismatchError, } from "./helm.js";
+export type { HelmInstallArgs, HelmInstallResult, HelmCapabilityProfile, HelmProfileAssertionOutcome, } from "./helm.js";
+export { probeClusterCapabilities, compareCapabilityProfile, ClusterProbeError } from "./cluster-probe.js";
+export type { LiveClusterCapabilities, DeclaredCapabilityProfile } from "./cluster-probe.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/op/activities/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACrC,YAAY,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,8BAA8B,EAC9B,yBAAyB,EACzB,0BAA0B,EAC1B,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,QAAQ,CAAC;AAChB,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACxG,YAAY,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/op/builders.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Typed step-builder wrappers for this lexicon's `helmInstall` activity
+ * (chant #1288 Stage 2 — "regenerate the step builders as fully typed
+ * wrappers"). Core cannot import a lexicon's `*Args` types (lexicons depend
+ * on core, not the other way around), so a fully typed `helmInstall` /
+ * `helmInstallPinned` has to live beside {@link HelmInstallArgs} — here,
+ * next to `./activities/helm.ts`. `opts`'s type in each wrapper below IS
+ * `HelmInstallArgs` itself (via `Omit`/`WithStepRefs`) — never a
+ * hand-restated mirror — so the option surface Stage 1's zod contracts
+ * deliberately skipped (`capabilityProfile`, `set`, `deleteMode`-adjacent
+ * cross-field options) is authoring-time typed for free.
+ *
+ * Every field also accepts a {@link StepOutputRef} in its place
+ * ({@link WithStepRefs}, chant #1950).
+ *
+ * `core`'s own `helmInstall`/`helmInstallPinned` (in `@intentius/chant/op`,
+ * re-exported from `@intentius/chant-lexicon-temporal`) are UNCHANGED and
+ * produce byte-identical `ActivityStep` output for the same inputs — these
+ * are purely additive. Deliberately not swapped into the temporal barrel
+ * (see `lexicons/k8s/src/op/builders.ts`'s module doc for why: it would make
+ * temporal depend on this package at runtime, undoing the product-agnostic
+ * split #809 did). An author who wants the typed surface imports it from
+ * here — `@intentius/chant-lexicon-helm` — which a project using
+ * `helmInstall` already depends on.
+ */
+import { type ActivityStep, type NamedActivityStep, type WithStepRefs } from "@intentius/chant/op";
+import type { HelmInstallArgs } from "./activities/helm.js";
+/** Extra opts every wrapper below accepts alongside its activity's own fields. */
+type StepOpts = {
+    profile?: ActivityStep["profile"];
+    id?: string;
+};
+/**
+ * Deploy a helm release — the fully typed twin of core's `helmInstall`.
+ * `opts` is {@link HelmInstallArgs} itself, minus the positional `name`/
+ * `chart`. Defaults to the `longInfra` profile.
+ */
+export declare const helmInstall: (name: string, chart: string, opts?: WithStepRefs<Omit<HelmInstallArgs, "name" | "chart">> & StepOpts) => NamedActivityStep;
+/**
+ * Deploy a recorded pinned render by its `sha256:` content digest (#1242) —
+ * the fully typed twin of core's `helmInstallPinned`. `opts` is
+ * {@link HelmInstallArgs} itself, minus the positional `name`/
+ * `contentDigest`. Defaults to the `longInfra` profile.
+ */
+export declare const helmInstallPinned: (name: string, contentDigest: string, opts?: WithStepRefs<Omit<HelmInstallArgs, "name" | "contentDigest">> & StepOpts) => NamedActivityStep;
+export {};
+//# sourceMappingURL=builders.d.ts.map

package/dist/op/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/op/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,kFAAkF;AAClF,KAAK,QAAQ,GAAG;IAAE,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,WAAW,GACtB,MAAM,MAAM,EACZ,OAAO,MAAM,EACb,OAAO,YAAY,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,QAAQ,KACtE,iBAGF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,MAAM,EACZ,eAAe,MAAM,EACrB,OAAO,YAAY,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC,GAAG,QAAQ,KAC9E,iBAGF,CAAC"}

package/dist/pinnability/actions.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Go template action extraction and control-flow scoping (#1234, epic #1228).
+ *
+ * The pinnability gate inspects template ACTIONS (`{{ ... }}`), never raw
+ * text. That distinction is finding 9: cert-manager carries 52 textual
+ * "lookup" occurrences, all comment prose, and a real template-action count
+ * of 0 — a text-matching gate refuses a chart that is perfectly pinnable.
+ *
+ * Beyond extraction, this module reconstructs the control-flow structure of a
+ * template file — which `if` / `with` / `range` blocks enclose each action —
+ * so the classifier can ask whether a construct is REACHABLE under the
+ * supplied values, not merely present. Reachability is what separates
+ * "unpinnable" from "pinnable with a recorded conditional hazard": bundled
+ * grafana's control-flow `lookup` sits behind `persistence.enabled`, off by
+ * default, so a default-values render never consults the cluster.
+ */
+export type ActionKind = "if" | "elseif" | "else" | "with" | "range" | "define" | "block" | "end" | "other";
+export interface TemplateAction {
+    /** Path of the file the action was found in (as given by the caller). */
+    file: string;
+    /** 1-based line the action starts on. */
+    line: number;
+    /** The action body between `{{` and `}}`, trim markers stripped. */
+    body: string;
+    /** Structural role of the action, from its leading keyword. */
+    kind: ActionKind;
+}
+/**
+ * One enclosing control-flow frame for an action. `conditions` are the
+ * expressions that must hold for the frame's branch to run; `negatedConditions`
+ * are prior branch conditions that must NOT hold (an `else` / `else if`
+ * branch runs only when every earlier branch condition was false).
+ */
+export interface ScopeFrame {
+    kind: "if" | "with" | "range" | "define" | "block" | "dependency-condition";
+    conditions: string[];
+    negatedConditions: string[];
+    /**
+     * When a `with` block pins the dot to a `.Values` subtree, the path of that
+     * subtree — so bare `.enabled` inside `with .Values.persistence` resolves
+     * to `persistence.enabled`. `undefined` means the dot is unresolvable
+     * (a `range` element, a non-values `with`, a `define` invoked from an
+     * unknown context).
+     */
+    dotValuesPath?: string[];
+    /** Dot is rebound to something we cannot resolve (range element etc.). */
+    dotUnresolvable?: boolean;
+}
+export interface ScopedAction {
+    action: TemplateAction;
+    /** Enclosing frames, outermost first. Empty for top-level actions. */
+    frames: ScopeFrame[];
+}
+/**
+ * Extract template actions from a source file, skipping comment actions
+ * (`{{/* ... *\/}}`). Text outside actions — including YAML `#` comments,
+ * where finding 9's 52 false positives lived — is never inspected by any
+ * scan built on this.
+ */
+export declare function extractActions(source: string, file: string): TemplateAction[];
+/**
+ * The pipeline of an action, structural keyword and variable assignment
+ * stripped: `if X` → `X`, `range $i, $v := X` → `X`, `$pw := X` → `X`.
+ * This is what condition evaluation and call-reachability parse.
+ */
+export declare function actionPipeline(action: TemplateAction): string;
+/**
+ * Walk a file's actions and attach the enclosing control-flow frames to each.
+ * `else` / `else if` branches carry the prior branch conditions as
+ * `negatedConditions`. Structure that cannot be tracked (an unbalanced
+ * `end`, template text split across files) degrades to fewer frames — which
+ * only ever makes the classifier MORE conservative, never less: a missing
+ * frame means a gate we cannot prove closed.
+ */
+export declare function scopeActions(actions: TemplateAction[]): ScopedAction[];
+//# sourceMappingURL=actions.d.ts.map

package/dist/pinnability/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/pinnability/actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,UAAU,GAClB,IAAI,GACJ,QAAQ,GACR,MAAM,GACN,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,GACP,KAAK,GACL,OAAO,CAAC;AAEZ,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,sBAAsB,CAAC;IAC5E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,0EAA0E;IAC1E,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,cAAc,CAAC;IACvB,sEAAsE;IACtE,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAaD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CAqC7E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAO7D;AAeD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,YAAY,EAAE,CAwGtE"}

package/dist/pinnability/classify.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The pinnability gate (#1234, epic #1228 Phase 1).
+ *
+ * A render is pinnable exactly when every input to it is closed. `helm
+ * template` has three inputs beyond (chart, values) that are silently
+ * defaulted or silently empty:
+ *
+ *   - cluster capabilities   — closable via --kube-version / --api-versions
+ *   - generated values       — closable by supplying the value as an input
+ *   - cluster state (lookup) — not closable offline
+ *
+ * The gate is therefore not "is this chart deterministic" but "are all of
+ * this render's inputs closed" — a property of `(chart, values)`, not of the
+ * chart alone. Concretely:
+ *
+ *   - A control-flow `lookup` that is REACHABLE under the supplied values is
+ *     a hard refusal: it changes which documents exist, and no value
+ *     substitution recovers that.
+ *   - A control-flow `lookup` the supplied values leave gated OFF is a
+ *     recorded conditional hazard, not a refusal — bundled grafana's
+ *     `lookup` behind `persistence.enabled: false` never runs, so the
+ *     render is pinnable; flipping that value re-classifies the pair.
+ *   - Value-position `lookup` is a declared-input requirement (epic
+ *     Decisions): it changes a field, not the document set.
+ *   - `.Capabilities.*` references require an explicit capability profile —
+ *     the default is a property of the helm BINARY (3.16.2 says v1.31.0,
+ *     4.1.1 says v1.35.0), so an unpinned render's digest depends on who
+ *     rendered it. 11 of the 13 survey charts hit this; it is the normal
+ *     case, not an error.
+ *   - Generated values (`randAlphaNum` and friends) are detected statically
+ *     and named; the double-render localizer (#1236) confirms them
+ *     dynamically. They classify as closable when a `.Values` path in the
+ *     same action can supply them.
+ *
+ * A chart that fails is refused with the specific construct and location,
+ * and keeps working unpinned. Adoption is incremental.
+ */
+import { type GatePath } from "./conditions.js";
+export type PinnabilityVerdict = "deterministic" | "pinnable" | "unpinnable";
+/** One `.Capabilities.*` reference; any of these makes a profile required. */
+export interface CapabilityRequirement {
+    file: string;
+    line: number;
+    capability: "KubeVersion" | "APIVersions";
+}
+/** An input that must be (or has been) closed for the render to pin. */
+export interface ClosedInput {
+    kind: "generated-value" | "value-position-lookup" | "supplied-values";
+    file?: string;
+    line?: number;
+    /** Template function for generated values (randAlphaNum, genCA, ...). */
+    fn?: string;
+    /** Root-scoped `.Values` path that can supply the input, when one exists. */
+    valuesPath?: string;
+    /** Can this input be closed by supplying a value at all? */
+    suppliable?: boolean;
+    detail: string;
+}
+/**
+ * A control-flow `lookup` the supplied values leave unreachable. Recorded —
+ * not refused — so that flipping the gating value later re-classifies the
+ * `(chart, values)` pair instead of silently changing which documents exist.
+ */
+export interface ConditionalHazard {
+    /** Instance scope in root coordinates ("" = the top-level chart, "grafana" = that subchart). */
+    chart: string;
+    file: string;
+    line: number;
+    /** The values path(s) currently gating the construct off, with their values. */
+    gates: GatePath[];
+    detail: string;
+}
+/** A control-flow `lookup` site, aggregated across chart instances. */
+export interface ControlFlowLookup {
+    file: string;
+    line: number;
+    action: string;
+    status: "refused" | "hazard";
+    /** Instance scopes the site was assessed in ("" = root). */
+    charts: string[];
+}
+export interface ValuePositionLookup {
+    file: string;
+    line: number;
+    action: string;
+}
+/** Evidence from an actual double render (#1236 owns producing this). */
+export interface RenderEvidence {
+    stable: boolean;
+    unstableLines: number;
+}
+export interface PinnabilityReport {
+    verdict: PinnabilityVerdict;
+    /** `.Capabilities.*` references, one entry per occurrence. Empty = no profile needed. */
+    requiresProfile: CapabilityRequirement[];
+    closedInputs: ClosedInput[];
+    hazards: ConditionalHazard[];
+    /** Human-readable summary; refusal reasons first, specific per construct. */
+    reasons: string[];
+    /** Raw lookup findings, for surfaces that need counts or locations. */
+    lookups: {
+        controlFlow: ControlFlowLookup[];
+        valuePosition: ValuePositionLookup[];
+    };
+    /** Non-fatal scan caveats (an unvendored dependency, etc.). */
+    warnings: string[];
+}
+export interface ClassifyChartOptions {
+    /** Values overrides, as `helm template --values` would merge them. */
+    values?: unknown;
+    /** Values files to load and merge (in order) over the chart defaults. */
+    valuesFiles?: string[];
+    /** Double-render evidence, when the caller has rendered. */
+    renderEvidence?: RenderEvidence;
+}
+/**
+ * Template files of ONE chart directory — `templates/` at any depth below
+ * it, excluding `charts/` (subcharts are their own instances) and NOTES.txt
+ * (rendered for the console, not the cluster).
+ */
+export declare function collectOwnTemplateFiles(chartDir: string): string[];
+/**
+ * Classify a chart directory against the values a render would be given.
+ * Subchart-recursive: dependencies vendored under `charts/` are scanned with
+ * their own effective values (aliases get their own scope, `condition:`-
+ * disabled dependencies gate their contents — findings 11 and 12).
+ */
+export declare function classifyChart(chartDir: string, options?: ClassifyChartOptions): PinnabilityReport;
+//# sourceMappingURL=classify.d.ts.map

package/dist/pinnability/classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../src/pinnability/classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAYH,OAAO,EAML,KAAK,QAAQ,EAEd,MAAM,cAAc,CAAC;AAStB,MAAM,MAAM,kBAAkB,GAAG,eAAe,GAAG,UAAU,GAAG,YAAY,CAAC;AAE7E,8EAA8E;AAC9E,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,aAAa,GAAG,aAAa,CAAC;CAC3C;AAED,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,iBAAiB,GAAG,uBAAuB,GAAG,iBAAiB,CAAC;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gGAAgG;IAChG,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC7B,4DAA4D;IAC5D,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,yFAAyF;IACzF,eAAe,EAAE,qBAAqB,EAAE,CAAC;IACzC,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,6EAA6E;IAC7E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,uEAAuE;IACvE,OAAO,EAAE;QACP,WAAW,EAAE,iBAAiB,EAAE,CAAC;QACjC,aAAa,EAAE,mBAAmB,EAAE,CAAC;KACtC,CAAC;IACF,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AA2DD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAiBlE;AA8FD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,oBAAyB,GACjC,iBAAiB,CAqPnB"}