@intentius/chant-lexicon-helm 0.124.30 → 0.124.32

package/dist/pinnability/values.js

@@ -0,0 +1,151 @@
+/**
+ * Chart model and value coalescing for the pinnability classifier (#1234,
+ * epic #1228).
+ *
+ * Pinnability is a property of `(chart, values)`, not of the chart alone —
+ * so the classifier needs each subchart instance's EFFECTIVE values to ask
+ * whether a gate is open. This module walks `Chart.yaml` dependencies
+ * (aliases and `condition:` included — finding 12: dependency conditions are
+ * values-driven and therefore closed inputs) and approximates helm's
+ * coalescing: child defaults, overridden by the parent's `<alias-or-name>`
+ * subtree, with `global` propagated down.
+ *
+ * The approximation is deliberate and bounded. `import-values`, `tags`, and
+ * `tpl`-computed values are not modeled; a gate they would decide resolves
+ * as UNKNOWN and the classifier refuses rather than pins (see
+ * conditions.ts). The build-time values probe (#1251) replaces this with
+ * helm's own coalescing.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+export function readChartMeta(chartDir) {
+    const raw = readYamlFile(join(chartDir, "Chart.yaml"));
+    const deps = [];
+    if (Array.isArray(raw?.dependencies)) {
+        for (const d of raw.dependencies) {
+            if (d === null || typeof d !== "object")
+                continue;
+            const dep = d;
+            if (typeof dep.name !== "string")
+                continue;
+            deps.push({
+                name: dep.name,
+                alias: typeof dep.alias === "string" ? dep.alias : undefined,
+                condition: typeof dep.condition === "string" ? dep.condition : undefined,
+            });
+        }
+    }
+    return {
+        name: typeof raw?.name === "string" ? raw.name : "",
+        dependencies: deps,
+    };
+}
+export function readYamlFile(path) {
+    if (!existsSync(path))
+        return undefined;
+    return yaml.load(readFileSync(path, "utf8"));
+}
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/**
+ * Helm-style deep merge: `override` wins, maps merge recursively, a `null`
+ * override deletes the key, arrays replace wholesale.
+ */
+export function mergeValues(base, override) {
+    if (override === undefined)
+        return base;
+    if (!isPlainObject(base) || !isPlainObject(override))
+        return override;
+    const out = { ...base };
+    for (const [k, v] of Object.entries(override)) {
+        if (v === null) {
+            delete out[k];
+            continue;
+        }
+        out[k] = k in out ? mergeValues(out[k], v) : v;
+    }
+    return out;
+}
+/** Resolve a dot path against a values tree; undefined when absent. */
+export function valueAtPath(values, path) {
+    let v = values;
+    for (const seg of path) {
+        if (!isPlainObject(v))
+            return undefined;
+        v = v[seg];
+    }
+    return v;
+}
+/**
+ * Build the instance tree for a chart directory and the values the render
+ * was given. `suppliedValues` merges over the root chart's `values.yaml`
+ * exactly like `helm template --values`.
+ */
+export function buildChartInstances(chartDir, suppliedValues) {
+    const warnings = [];
+    const rootDefaults = readYamlFile(join(chartDir, "values.yaml")) ?? {};
+    const rootValues = mergeValues(rootDefaults, suppliedValues);
+    const instances = [];
+    const visit = (dir, relDir, scope, values, disabledBy) => {
+        instances.push({ dir, relDir, scope, values, disabledBy });
+        const meta = readChartMeta(dir);
+        const chartsDir = join(dir, "charts");
+        const childDirs = existsSync(chartsDir)
+            ? readdirSync(chartsDir).filter((e) => {
+                const p = join(chartsDir, e);
+                return statSync(p).isDirectory() && existsSync(join(p, "Chart.yaml"));
+            })
+            : [];
+        const declared = new Set();
+        const visitChild = (dep) => {
+            const key = dep.alias ?? dep.name;
+            const childDir = join(chartsDir, dep.name);
+            if (!existsSync(join(childDir, "Chart.yaml"))) {
+                warnings.push(`dependency ${dep.name} of ${relDir === "" ? "the chart" : relDir} is not vendored under charts/ — not scanned`);
+                return;
+            }
+            declared.add(dep.name);
+            // Condition paths are resolved against the TOP parent's values
+            // (helm's documented semantics); first present path wins, absent
+            // conditions leave the dependency enabled.
+            let childDisabledBy = disabledBy;
+            if (childDisabledBy === undefined && dep.condition !== undefined) {
+                for (const rawPath of dep.condition.split(",")) {
+                    const path = rawPath.trim();
+                    if (path === "")
+                        continue;
+                    const v = valueAtPath(rootValues, path.split("."));
+                    if (v === undefined)
+                        continue;
+                    if (v === false)
+                        childDisabledBy = path;
+                    break;
+                }
+            }
+            const childDefaults = readYamlFile(join(childDir, "values.yaml")) ?? {};
+            const parentSlice = isPlainObject(values) ? values[key] : undefined;
+            let childValues = mergeValues(childDefaults, parentSlice);
+            // Globals propagate into every subchart tree.
+            const parentGlobal = isPlainObject(values) ? values.global : undefined;
+            if (parentGlobal !== undefined && isPlainObject(childValues)) {
+                childValues = {
+                    ...childValues,
+                    global: mergeValues(childValues.global, parentGlobal),
+                };
+            }
+            visit(childDir, relDir === "" ? `charts/${dep.name}` : `${relDir}/charts/${dep.name}`, [...scope, key], childValues, childDisabledBy);
+        };
+        for (const dep of meta.dependencies)
+            visitChild(dep);
+        // charts/ directories not declared in Chart.yaml are implicit,
+        // always-enabled dependencies.
+        for (const name of childDirs) {
+            if (!declared.has(name))
+                visitChild({ name });
+        }
+    };
+    visit(chartDir, "", [], rootValues, undefined);
+    return { instances, warnings };
+}

package/dist/plugin.js

@@ -0,0 +1,458 @@
+/**
+ * Helm lexicon plugin.
+ *
+ * Implements the LexiconPlugin interface with the Helm chart serializer,
+ * Helm-specific intrinsics, lint rules, and post-synth checks.
+ */
+import { compositeCatalog } from "./composites/catalog.js";
+import { helmCommandGroup } from "./commands.js";
+import { detectTemplate } from "./detect.js";
+import { discoverLintRules } from "@intentius/chant/lint/discover";
+import { postSynthChecks as postSynthCheckList } from "./lint/post-synth/index.js";
+import { helmAuditCatalog } from "./lint/audit-catalog.js";
+import { createSkillsLoader, createDiffTool } from "@intentius/chant/lexicon-plugin-helpers";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { helmSerializer } from "./serializer.js";
+import { helmCompletions } from "./lsp/completions.js";
+import { helmHover } from "./lsp/hover.js";
+import { helmConfigSchema } from "./config.js";
+import { helmProjectCodegen } from "./project-codegen.js";
+import { helmDeepNormalizationHooks } from "./deep-observe-hooks.js";
+import { LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+export const helmPlugin = {
+    name: "helm",
+    // The `helm` namespace in chant.config.ts — capability profiles (#1235).
+    // Declaring the schema makes core validate the namespace at load, so a
+    // typo'd profile field fails the build instead of silently unpinning.
+    configSchema: helmConfigSchema,
+    // Typed values and a render factory per chart in `helm.charts`, written by
+    // `chant generate` and checked for drift by every build. See
+    // ./project-codegen.ts.
+    projectCodegen: () => helmProjectCodegen(),
+    // #1246 — helm resolves real ownership verdicts on the thin read (every row
+    // is release-scoped, so helm-managed = owned via release identity), and the
+    // deep read (#1247) delegates to the k8s reader, which resolves the shared
+    // label channel (`app.kubernetes.io/managed-by` + `chant.intentius.io/*`)
+    // on the live objects.
+    ownershipChannel: { keys: LABEL_OWNERSHIP_KEYS, reads: ["describeResources", "observeResourcesDeep"] },
+    auditCatalog: () => helmAuditCatalog,
+    serializer: helmSerializer,
+    // #1248 (epic #1228 Phase 6, via the #1078 seam) — `chant helm` mounts the
+    // pinned-render surface: the pinnability gate (#1234), the double-render
+    // localizer (#1236), and the recorded-render listing with digests (#1237).
+    // See ./commands.ts for the verb list; this plugin only mounts it. The
+    // diff verbs (#1249 render-to-render, #1250 render-to-live, both mounted on
+    // "diff") land there.
+    commands() {
+        return helmCommandGroup();
+    },
+    lintRules() {
+        const rulesDir = join(dirname(fileURLToPath(import.meta.url)), "lint", "rules");
+        return discoverLintRules(rulesDir, import.meta.url);
+    },
+    postSynthChecks() {
+        return postSynthCheckList;
+    },
+    // The providers themselves have lived in src/lsp/ with tests since the
+    // lexicon was written; they were never registered here, so `chant serve lsp`
+    // never reached them (#1342).
+    completionProvider: helmCompletions,
+    hoverProvider: helmHover,
+    // chant #1174 — `foldsAsCall: true` opts an intrinsic's PLAIN-CALL form
+    // into `chant build --fold` (chant #1044's mechanism, previously unused by
+    // this lexicon: every helm intrinsic is a plain call — helm has no tagged
+    // templates at all — so before this PR NONE of them folded, and a single
+    // `include(...)`/`printf(...)` anywhere in a chart's resources forced the
+    // whole file back to the run path).
+    //
+    // Audited one at a time against `IntrinsicDef.foldsAsCall`'s criterion
+    // (../../../packages/core/src/lexicon.ts): "calling the intrinsic is a
+    // pure function of its arguments that builds a deterministic data
+    // envelope". Every function below (`include`/`required`/`helmDefault`/
+    // `toYaml`/`quote`/`printf`/`tpl`/`lookup`/`filesGet`/`filesGlob`/
+    // `filesAsConfig`/`filesAsSecrets`, ./intrinsics.ts) does exactly that: it
+    // builds a `HelmTpl` (or, for `lookup`, a string) by interpolating its
+    // arguments into a Go template expression string — no I/O, no mutation, no
+    // dependency on anything but the arguments. `lookup`'s own side effect
+    // (a live cluster read) happens when HELM renders the resulting template
+    // at deploy time, not when this JS function runs at `chant build` time, so
+    // it is just as pure here as the rest.
+    //
+    // Left OUT, each for a specific reason rather than an oversight:
+    //   - `values`/`Release`/`ChartRef`/`Capabilities`/`Template` are proxy
+    //     OBJECTS, never called (`values(...)` isn't valid source) — nothing
+    //     to opt in.
+    //   - `withOrder`/`argoWave` return a PLAIN record meant to be spread
+    //     (`{...withOrder(1)}`), not a `HelmTpl`. `fold()`'s object-spread
+    //     handling (`Object.assign(obj, src)`, ../fold/fold.ts) runs
+    //     SYNCHRONOUSLY on the immediately-folded value, before the async
+    //     revival that would turn a folded call into its real result — opting
+    //     these in would spread the folded `{__intrinsic, args}` envelope's
+    //     own keys into the object instead of the real record. A real
+    //     soundness hazard, not a "not yet audited."
+    //   - `If`/`ElseIf`/`Range`/`With` take an arbitrary `body`/`elseBody`
+    //     that is often an arrow function (`Range(list, (item) => ({...}))`)
+    //     or a nested Declarable — `fold()` already rejects a function used as
+    //     a value on its own terms, so opting these in buys nothing measured
+    //     on this corpus and is left for a future PR to size against real
+    //     usage rather than widened on speculation.
+    intrinsics() {
+        return [
+            { name: "values", description: "Proxy accessor for {{ .Values.x }} references", isTag: false },
+            { name: "Release", description: "Built-in Release object (Name, Namespace, etc.)", isTag: false },
+            { name: "ChartRef", description: "Built-in Chart object (Name, Version, AppVersion)", isTag: false },
+            { name: "include", description: 'Include a named template: {{ include "name" . }}', isTag: false, foldsAsCall: true },
+            { name: "required", description: 'Require a value: {{ required "msg" .Values.x }}', isTag: false, foldsAsCall: true },
+            { name: "helmDefault", description: 'Default value: {{ default "def" .Values.x }}', isTag: false, foldsAsCall: true },
+            { name: "toYaml", description: "Convert to YAML: {{ toYaml .Values.x | nindent N }}", isTag: false, foldsAsCall: true },
+            { name: "quote", description: "Quote a value: {{ .Values.x | quote }}", isTag: false, foldsAsCall: true },
+            { name: "printf", description: 'Format string: {{ printf "%s" .Values.x }}', isTag: false, foldsAsCall: true },
+            { name: "tpl", description: "Evaluate template: {{ tpl .Values.x . }}", isTag: false, foldsAsCall: true },
+            { name: "lookup", description: 'Lookup resource: {{ lookup "v1" "Secret" "ns" "name" }}', isTag: false, foldsAsCall: true },
+            { name: "Capabilities", description: "Built-in Capabilities object (KubeVersion, APIVersions, HelmVersion)", isTag: false },
+            { name: "Template", description: "Built-in Template object (Name, BasePath)", isTag: false },
+            { name: "filesGet", description: '.Files.Get: {{ .Files.Get "path" }}', isTag: false, foldsAsCall: true },
+            { name: "filesGlob", description: '.Files.Glob: {{ .Files.Glob "pattern" }}', isTag: false, foldsAsCall: true },
+            { name: "filesAsConfig", description: ".Files.Glob.AsConfig for ConfigMap data", isTag: false, foldsAsCall: true },
+            { name: "filesAsSecrets", description: ".Files.Glob.AsSecrets for Secret data", isTag: false, foldsAsCall: true },
+            { name: "ElseIf", description: "Else-if chaining: {{- else if .Values.x }}...{{- end }}", isTag: false },
+            { name: "If", description: "Conditional: {{- if .Values.x }}...{{- end }}", isTag: false },
+            { name: "Range", description: "Range loop: {{- range .Values.x }}...{{- end }}", isTag: false },
+            { name: "With", description: "With scope: {{- with .Values.x }}...{{- end }}", isTag: false },
+            { name: "withOrder", description: "Helm hook annotations for resource ordering (pre-install/pre-upgrade)", isTag: false },
+            { name: "argoWave", description: "Argo CD sync wave annotation", isTag: false },
+        ];
+    },
+    detectTemplate,
+    composites() {
+        return compositeCatalog;
+    },
+    mcpTools() {
+        return [createDiffTool(helmSerializer, "Compare current Helm chart build output against previous output", "helm")];
+    },
+    mcpResources() {
+        return [
+            {
+                uri: "helm:resource-catalog",
+                name: "Helm Chart Resource Catalog",
+                description: "JSON list of all supported Helm chart resource types",
+                mimeType: "application/json",
+                async handler() {
+                    const { readFileSync } = await import("fs");
+                    const { join, dirname } = await import("path");
+                    const { fileURLToPath } = await import("url");
+                    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+                    try {
+                        const lexicon = JSON.parse(readFileSync(join(pkgDir, "dist", "meta.json"), "utf-8"));
+                        const entries = Object.entries(lexicon).map(([className, entry]) => ({
+                            className,
+                            resourceType: entry.resourceType,
+                            kind: entry.kind,
+                        }));
+                        return JSON.stringify(entries);
+                    }
+                    catch {
+                        return JSON.stringify([{ className: "Chart", kind: "resource" }, { className: "Values", kind: "resource" }, { className: "HelmNotes", kind: "resource" }]);
+                    }
+                },
+            },
+            {
+                uri: "examples/web-app",
+                name: "Web App Helm Chart Example",
+                description: "A basic web application Helm chart with Deployment, Service, and Ingress",
+                mimeType: "text/typescript",
+                async handler() {
+                    return `import { Chart, Values, HelmNotes } from "@intentius/chant-lexicon-helm";
+import { values, Release, include, toYaml, printf } from "@intentius/chant-lexicon-helm/intrinsics";
+import { Deployment, Service, Ingress } from "@intentius/chant-lexicon-k8s";
+
+export const chart = new Chart({
+  apiVersion: "v2",
+  name: "web-app",
+  version: "0.1.0",
+  appVersion: "1.0.0",
+  type: "application",
+  description: "A web application chart",
+});
+
+export const valuesSchema = new Values({
+  replicaCount: 2,
+  image: { repository: "nginx", tag: "latest", pullPolicy: "IfNotPresent" },
+  service: { type: "ClusterIP", port: 80 },
+  ingress: { enabled: false, host: "example.com" },
+});
+
+export const deployment = new Deployment({
+  metadata: { name: include("web-app.fullname"), labels: include("web-app.labels") },
+  spec: {
+    replicas: values.replicaCount,
+    selector: { matchLabels: include("web-app.selectorLabels") },
+    template: {
+      metadata: { labels: include("web-app.selectorLabels") },
+      spec: {
+        containers: [{
+          name: "web-app",
+          image: printf("%s:%s", values.image.repository, values.image.tag),
+          ports: [{ containerPort: values.service.port, name: "http" }],
+        }],
+      },
+    },
+  },
+});
+
+export const service = new Service({
+  metadata: { name: include("web-app.fullname"), labels: include("web-app.labels") },
+  spec: {
+    type: values.service.type,
+    ports: [{ port: values.service.port, targetPort: "http", protocol: "TCP", name: "http" }],
+    selector: include("web-app.selectorLabels"),
+  },
+});
+`;
+                },
+            },
+        ];
+    },
+    initTemplates(_template) {
+        if (_template === "stateful-service") {
+            return {
+                src: {
+                    "chart.ts": `import { Chart, Values, HelmNotes } from "@intentius/chant-lexicon-helm";
+import { values, Release, include, toYaml, printf } from "@intentius/chant-lexicon-helm/intrinsics";
+import { StatefulSet, Service, PersistentVolumeClaim, ConfigMap } from "@intentius/chant-lexicon-k8s";
+
+export const chart = new Chart({
+  apiVersion: "v2",
+  name: "my-stateful-app",
+  version: "0.1.0",
+  appVersion: "1.0.0",
+  type: "application",
+  description: "A Helm chart for a stateful application",
+});
+
+export const valuesSchema = new Values({
+  replicaCount: 3,
+  image: {
+    repository: "postgres",
+    tag: "16",
+    pullPolicy: "IfNotPresent",
+  },
+  service: {
+    port: 5432,
+  },
+  storage: {
+    size: "10Gi",
+    storageClass: "",
+  },
+  config: {
+    maxConnections: "100",
+    sharedBuffers: "256MB",
+  },
+});
+
+export const configMap = new ConfigMap({
+  metadata: {
+    name: include("my-stateful-app.fullname"),
+    labels: include("my-stateful-app.labels"),
+  },
+  data: {
+    "max_connections": values.config.maxConnections,
+    "shared_buffers": values.config.sharedBuffers,
+  },
+});
+
+export const headlessService = new Service({
+  metadata: {
+    name: printf("%s-headless", include("my-stateful-app.fullname")),
+    labels: include("my-stateful-app.labels"),
+  },
+  spec: {
+    type: "ClusterIP",
+    clusterIP: "None",
+    ports: [{ port: values.service.port, targetPort: "db", protocol: "TCP", name: "db" }],
+    selector: include("my-stateful-app.selectorLabels"),
+  },
+});
+
+export const statefulSet = new StatefulSet({
+  metadata: {
+    name: include("my-stateful-app.fullname"),
+    labels: include("my-stateful-app.labels"),
+  },
+  spec: {
+    serviceName: printf("%s-headless", include("my-stateful-app.fullname")),
+    replicas: values.replicaCount,
+    selector: { matchLabels: include("my-stateful-app.selectorLabels") },
+    template: {
+      metadata: { labels: include("my-stateful-app.selectorLabels") },
+      spec: {
+        containers: [{
+          name: "db",
+          image: printf("%s:%s", values.image.repository, values.image.tag),
+          ports: [{ containerPort: values.service.port, name: "db" }],
+          volumeMounts: [{ name: "data", mountPath: "/var/lib/postgresql/data" }],
+        }],
+      },
+    },
+    volumeClaimTemplates: [
+      new PersistentVolumeClaim({
+        metadata: { name: "data" },
+        spec: {
+          accessModes: ["ReadWriteOnce"],
+          resources: { requests: { storage: values.storage.size } },
+        },
+      }),
+    ],
+  },
+});
+`,
+                },
+            };
+        }
+        return {
+            src: {
+                "chart.ts": `import { Chart, Values, HelmNotes } from "@intentius/chant-lexicon-helm";
+import { values, Release, include, toYaml, printf } from "@intentius/chant-lexicon-helm/intrinsics";
+import { Deployment, Service } from "@intentius/chant-lexicon-k8s";
+
+export const chart = new Chart({
+  apiVersion: "v2",
+  name: "my-app",
+  version: "0.1.0",
+  appVersion: "1.0.0",
+  type: "application",
+  description: "A Helm chart for my application",
+});
+
+export const valuesSchema = new Values({
+  replicaCount: 1,
+  image: {
+    repository: "nginx",
+    tag: "",
+    pullPolicy: "IfNotPresent",
+  },
+  service: {
+    type: "ClusterIP",
+    port: 80,
+  },
+});
+
+export const deployment = new Deployment({
+  metadata: {
+    name: include("my-app.fullname"),
+    labels: include("my-app.labels"),
+  },
+  spec: {
+    replicas: values.replicaCount,
+    selector: {
+      matchLabels: include("my-app.selectorLabels"),
+    },
+    template: {
+      metadata: {
+        labels: include("my-app.selectorLabels"),
+      },
+      spec: {
+        containers: [{
+          name: "my-app",
+          image: printf("%s:%s", values.image.repository, values.image.tag),
+          ports: [{ containerPort: values.service.port, name: "http" }],
+        }],
+      },
+    },
+  },
+});
+
+export const service = new Service({
+  metadata: {
+    name: include("my-app.fullname"),
+    labels: include("my-app.labels"),
+  },
+  spec: {
+    type: values.service.type,
+    ports: [{
+      port: values.service.port,
+      targetPort: "http",
+      protocol: "TCP",
+      name: "http",
+    }],
+    selector: include("my-app.selectorLabels"),
+  },
+});
+`,
+            },
+        };
+    },
+    skills: createSkillsLoader(import.meta.url, [
+        { file: "chant-helm.md", name: "chant-helm", description: "Build, validate, and package Helm charts from a chant project" },
+        { file: "chant-helm-patterns.md", name: "chant-helm-patterns", description: "Common Helm chart patterns and best practices using chant" },
+        { file: "chant-helm-security.md", name: "chant-helm-security", description: "Security best practices for Helm charts built with chant" },
+    ]),
+    async docs(options) {
+        const { generateDocs } = await import("./codegen/docs.js");
+        await generateDocs({ verbose: options?.verbose });
+    },
+    async generate(options) {
+        const { generate, writeGeneratedFiles } = await import("./codegen/generate.js");
+        const { dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const result = await generate({ verbose: options?.verbose ?? true });
+        const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+        writeGeneratedFiles(result, pkgDir);
+        console.error(`Generated ${result.resources} resources, ${result.properties} property types`);
+    },
+    async validate(options) {
+        const { validate } = await import("./validate.js");
+        const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+        const result = await validate();
+        printValidationResult(result);
+    },
+    async coverage(options) {
+        const { analyzeHelmCoverage } = await import("./coverage.js");
+        await analyzeHelmCoverage({
+            verbose: options?.verbose,
+            minOverall: options?.minOverall,
+        });
+    },
+    async package(options) {
+        const { packageLexicon } = await import("./codegen/package.js");
+        const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+        const { join, dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const { spec, stats } = await packageLexicon({ verbose: options?.verbose, force: options?.force });
+        const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+        const distDir = join(pkgDir, "dist");
+        writeBundleSpec(spec, distDir);
+        console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+    },
+    async listArtifacts(options) {
+        const { listArtifacts } = await import("./list-artifacts.js");
+        return listArtifacts(options);
+    },
+    // #1246 — per-resource observation of what each declared chart's release
+    // holds (`helm get manifest` + `helm get hooks`, both channels), with total
+    // tri-state verdicts. This is what gives `lifecycle diff --live` helm rows.
+    async describeResources(options) {
+        const { describeResources } = await import("./describe-resources.js");
+        return describeResources(options);
+    },
+    // #1247 — deep property-level trees for the release's resources, read live
+    // through the k8s lexicon's typed client and normalized by its hooks.
+    // Dynamic import for the same reason k8s's is: the reader reaches
+    // `@intentius/chant-k8s-client`, which must stay off the build path.
+    async observeResourcesDeep(options) {
+        const { observeResourcesDeepHelm } = await import("./deep-observe.js");
+        return observeResourcesDeepHelm(options);
+    },
+    // The k8s lexicon's hooks by reference, not a copy (#1247) — the objects a
+    // release deploys are Kubernetes objects, and core normalizes the declared
+    // tree with the same rules the reader used.
+    deepNormalizationHooks: helmDeepNormalizationHooks,
+    // #1495 piece 4 — the deploy-unit observer for helm-upgrade units: a
+    // release's presence and native status, read back by the same name the
+    // capability deploys under. Dynamic import mirrors listArtifacts.
+    async describeStackStatus(options) {
+        const { describeStackStatus } = await import("./describe-stack-status.js");
+        return describeStackStatus(options);
+    },
+};