@intentius/chant-lexicon-helm 0.45.0 → 0.49.0

package/dist/render-digest.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"render-digest.d.ts","sourceRoot":"","sources":["../src/render-digest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAQH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CACtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAarE;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoB3D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,mFAAmF;AACnF,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,8DAA8D;IAC9D,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC,8EAA8E;IAC9E,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,qBAAqB,CAwB3F"}

package/dist/render-store.d.ts

@@ -0,0 +1,310 @@
+/**
+ * RenderManifest + content-addressed render storage (#1238, epic #1228
+ * Phase 2).
+ *
+ * #1237 gave a pinned render its identities — `inputDigest` over the
+ * declared inputs, `contentDigest` over the canonical rendered bytes. This
+ * module makes the render durable: the canonical bytes land in a
+ * content-addressed store keyed by `contentDigest`, and a `RenderManifest`
+ * — modeled on core's `BuildArchiveManifest`
+ * (packages/core/src/components/verbs/build-archive.ts) — records what the
+ * bytes are, what produced them, and how to find each document inside them.
+ *
+ * Storage layout, under `~/.chant/helm-renders/` (override with
+ * `CHANT_HELM_RENDER_ROOT`):
+ *
+ * ```
+ * sha256-<64 hex>/          one per distinct contentDigest
+ *   content.yaml            the canonical rendered bytes (canonicalizeRender)
+ *   manifest.json           the RenderManifest
+ * inputs/<64 hex>.json      inputs index: full-render-inputs key -> digests
+ * ```
+ *
+ * The `sha256-<hex>` entries are the new root the issue asks for: the
+ * pre-#1238 cache keyed entries by a *truncated, input-derived* hash
+ * (16 hex characters, no algorithm prefix), which is a cache key, not an
+ * artifact identity. Those legacy entries are left exactly where they are —
+ * unpinned renders keep using them — and pinned renders write here instead.
+ * No migration: a truncated key cannot be turned back into a digest.
+ *
+ * Two renders that produce the same bytes share one `sha256-<hex>` entry —
+ * the content file and manifest are written once and never rewritten
+ * (first writer wins; the store is immutable, like a build archive entry).
+ * Dedup falls out of content addressing rather than being a feature.
+ *
+ * The inputs index preserves cache-hit behavior: before shelling out to
+ * helm, `HelmRender` computes the full-inputs key and reads
+ * `inputs/<key>.json` to find the bytes a previous identical render stored.
+ * The index key deliberately differs from `inputDigest`: the release name
+ * and namespace are baked into the rendered bytes (`.Release.Name`,
+ * `--namespace`) but are excluded from `inputDigest` because the release
+ * ledger uses that digest as a cross-environment join key (see
+ * `helmInputDigest` in ./render-digest.ts). A cache must key on everything
+ * that changes the bytes, so the index key includes both.
+ *
+ * Retention: none, deliberately. The build archive this is modeled on has
+ * no garbage collection — an archive entry lives until someone deletes it —
+ * and the pre-#1238 render cache behaved the same way. This store follows
+ * suit: entries accumulate until removed by hand. If the archive ever grows
+ * a retention story, this store should adopt the same one.
+ */
+import type { HelmCapabilityProfile } from "./config.js";
+import type { ValueOrigin } from "./values-probe.js";
+/**
+ * One document's entry in a render's document index: enough identity to ask
+ * "give me the ServiceAccount named X in namespace Y" and enough addressing
+ * to answer it without parsing the whole stream.
+ */
+export interface RenderDocumentEntry {
+    /** Kubernetes kind, e.g. `Deployment`. */
+    kind: string;
+    /** apiVersion as rendered, e.g. `apps/v1`. */
+    apiVersion: string;
+    /** `metadata.name`. */
+    name: string;
+    /** `metadata.namespace`, or `null` for cluster-scoped / namespace-less documents. */
+    namespace: string | null;
+    /** The helm-inserted `# Source:` origin path, when the document carries one. */
+    source: string | null;
+    /**
+     * Byte offset of this document's first byte inside `content.yaml`
+     * (pointing just past the `---` separator line, at the `# Source:` header
+     * when there is one).
+     */
+    start: number;
+    /** Byte length of the document, up to the next separator (or end of file). */
+    length: number;
+    /** `sha256:` over exactly those bytes — lets a reader verify a slice without trusting offsets. */
+    digest: string;
+}
+/**
+ * The durable record of one pinned render — what `manifest.json` holds.
+ * Modeled on `BuildArchiveManifest`: versioned, content-addressed, and
+ * carrying both identity sides the epic's Decisions require — the
+ * input-side join key (`inputDigest`, with `valuesDigest` as its
+ * values-only component) for cross-environment questions, and
+ * `contentDigest` proving what this cluster's profile actually received.
+ */
+export interface RenderManifest {
+    /** Manifest schema version, so an incompatible future shape is detected before being misread. */
+    version: 1;
+    /** Chart name or local chart path, as the render declared it. */
+    chart: string;
+    /** Pinned chart version, or `null` for a local chart rendered without one. */
+    chartVersion: string | null;
+    /** Chart repo URL, or `null` for a local chart. */
+    repo: string | null;
+    /** Helm release name baked into the bytes (`.Release.Name`). */
+    releaseName: string;
+    /** Namespace the render targeted (`--namespace`), or `null`. */
+    namespace: string | null;
+    /**
+     * `sha256:` over the canonical JSON of the resolved values alone — the
+     * input-side join key the epic's ledger queries use together with
+     * `(chart, chartVersion)`.
+     */
+    valuesDigest: string;
+    /**
+     * `sha256:` over the full declared-input set (chart reference, version,
+     * values, capability facts) — `helmInputDigest`, the same digest the
+     * release ledger records on deploy (#1243).
+     */
+    inputDigest: string;
+    /** The capability profile the render was pinned against. `cluster` is the profile's declared name — profiles are per cluster. */
+    capabilityProfile: {
+        cluster: string;
+        kubeVersion: string;
+        apiVersions: string[];
+    };
+    /** `sha256:` over the canonical rendered bytes — the artifact identity, and this entry's storage key. */
+    contentDigest: string;
+    /** Number of documents in the canonical stream (including any the index could not identify). */
+    docCount: number;
+    /** Index of identifiable documents: kind/namespace/name -> byte span + per-document digest. */
+    documents: RenderDocumentEntry[];
+    /** ISO-8601 timestamp this manifest was written. Not part of any digest. */
+    renderedAt: string;
+    /**
+     * Version of the helm binary that produced the bytes. Load-bearing: the
+     * default kube version is a property of the binary (epic finding 1), so
+     * this field is what explains a digest mismatch between two machines.
+     */
+    helmVersion: string;
+    /** chant version that wrote this manifest. */
+    chantVersion: string;
+    /** Source ref/commit the render was produced from, when the caller supplied one. */
+    sourceRef: string | null;
+    /**
+     * `sha256:` over the canonical JSON of the coalesced values the
+     * build-time probe (#1251) observed for every chart instance, keyed by
+     * scope path — `coalescedValuesDigest` from `./values-probe.ts`. `null`
+     * when the probe did not run for this render (a repo-fetched chart, whose
+     * source the probe needs on disk, or a probe failure — never fabricated).
+     */
+    coalescedValuesDigest: string | null;
+    /**
+     * Each coalesced value's winning layer (#1252), dot-joined root-coordinate
+     * path to `ValueOrigin` — `computeValueSources` from `./values-probe.ts`.
+     * `null` under the same conditions as `coalescedValuesDigest`.
+     */
+    valueSources: Record<string, ValueOrigin> | null;
+}
+/** What `inputs/<key>.json` holds: the digests a full-inputs cache key resolves to. */
+export interface RenderInputsIndexEntry {
+    version: 1;
+    inputDigest: string;
+    contentDigest: string;
+}
+/**
+ * Root of the render store. `CHANT_HELM_RENDER_ROOT` overrides the default
+ * `~/.chant/helm-renders` — the same directory the legacy input-keyed cache
+ * lives in; the two coexist because legacy entries are bare 16-hex names
+ * and store entries are `sha256-` prefixed.
+ */
+export declare function renderStoreRoot(): string;
+/** The full set of inputs that determine a pinned render's bytes. */
+export interface RenderCacheKeySource {
+    /** Chart reference — a local path, or `<repo-url>/<chart>` for repo-fetched charts (same convention `helmInputDigest` uses). */
+    chart: string;
+    chartVersion?: string;
+    /** Release name — baked into the bytes via `.Release.Name`, so a real cache input even though `inputDigest` excludes it. */
+    releaseName: string;
+    /** Namespace — baked in via `--namespace`, likewise excluded from `inputDigest`. */
+    namespace?: string;
+    values?: Record<string, unknown>;
+    capabilityProfile: HelmCapabilityProfile;
+}
+/**
+ * Cache key over *everything* that changes a pinned render's bytes — a
+ * strict superset of `helmInputDigest`'s inputs (adds release name,
+ * namespace, and the profile's declared name, mirroring the legacy cache
+ * key's fields). 64 hex characters, no prefix: this is a lookup key, not an
+ * artifact identity.
+ */
+export declare function renderCacheKey(source: RenderCacheKeySource): string;
+/**
+ * `sha256:` over the canonical JSON of the resolved values alone — the
+ * `valuesDigest` half of the ledger's input-side join key
+ * `(chart, chartVersion, valuesDigest)`. Absent values digest as `{}`,
+ * matching `helmInputDigest`'s treatment.
+ */
+export declare function helmValuesDigest(values?: Record<string, unknown>): string;
+/**
+ * Build the document index over a canonical stream: for every identifiable
+ * document (it parses and carries `kind` + `metadata.name`), its
+ * kind/namespace/name identity, byte span, and per-document digest.
+ * Returns the index and the total document count — the count includes
+ * documents the index could not identify, so `docCount` is always the
+ * number of documents the artifact carries.
+ */
+export declare function indexRenderDocuments(canonical: string): {
+    documents: RenderDocumentEntry[];
+    docCount: number;
+};
+export interface PersistHelmRenderInput {
+    /** The `helm template` output — raw or already canonical; it is canonicalized before storage either way. */
+    rendered: string;
+    /** Release name the render was produced under (`HelmRenderProps.name`). */
+    releaseName: string;
+    /** Chart name or local chart path, as declared. */
+    chart: string;
+    /** Chart repo URL for repo-fetched charts. */
+    repo?: string;
+    chartVersion?: string;
+    namespace?: string;
+    values?: Record<string, unknown>;
+    /**
+     * The capability profile the render was pinned against. Absent means the
+     * render was unpinned — persistence is refused, because an unpinned
+     * render's bytes are a function of the local helm binary's defaults and
+     * have no identity worth storing.
+     */
+    capabilityProfile?: HelmCapabilityProfile;
+    /** Version of the helm binary that produced the bytes. Recorded as `"unknown"` when not supplied. */
+    helmVersion?: string;
+    /** Source ref/commit, when the caller has one. Never fabricated. */
+    sourceRef?: string;
+    /**
+     * The build-time coalesced-values probe's digest (#1251), when the caller
+     * ran one for this render. Absent (not merely `undefined`-passed) records
+     * `null` in the manifest — the probe needs the chart source on disk, so a
+     * repo-fetched render legitimately has none.
+     */
+    coalescedValuesDigest?: string;
+    /** The probe's value-source attribution (#1252), alongside `coalescedValuesDigest`. */
+    valueSources?: Record<string, ValueOrigin>;
+    /** Clock override for tests. */
+    now?: () => Date;
+    /** Store root override; defaults to `renderStoreRoot()`. */
+    root?: string;
+}
+export interface PersistedHelmRender {
+    /** The manifest now on disk — the existing one when the content was already stored. */
+    manifest: RenderManifest;
+    /** Directory the render lives in: `<root>/sha256-<hex>`. */
+    dir: string;
+    /**
+     * True when this contentDigest was already in the store — the bytes and
+     * manifest were left untouched (only the inputs index was updated).
+     */
+    deduplicated: boolean;
+}
+/**
+ * Persist one pinned render: canonical bytes under their `contentDigest`,
+ * the `RenderManifest` beside them, and an inputs-index entry so an
+ * identical future render is a cache hit.
+ *
+ * Content-addressed entries are immutable: when the digest directory
+ * already holds a manifest, both files are left as they are and the
+ * existing manifest is returned (`deduplicated: true`). The inputs index is
+ * still written — a new input combination can legitimately map to bytes the
+ * store already holds.
+ *
+ * Refuses an unpinned render (no capability profile) with the specific
+ * reason: no profile means the bytes depend on the local helm binary's
+ * defaulted capabilities, so they have no stable content identity to store
+ * under.
+ */
+export declare function persistHelmRender(input: PersistHelmRenderInput): PersistedHelmRender;
+/** Load the `RenderManifest` stored under a content digest, or `undefined` when the store has no such entry. */
+export declare function loadRenderManifest(contentDigest: string, opts?: {
+    root?: string;
+}): RenderManifest | undefined;
+/** Load the canonical rendered bytes stored under a content digest, or `undefined` when absent. */
+export declare function loadRenderContent(contentDigest: string, opts?: {
+    root?: string;
+}): string | undefined;
+/** Resolve a full-inputs cache key through the inputs index, or `undefined` on a miss. */
+export declare function findRenderByCacheKey(cacheKey: string, opts?: {
+    root?: string;
+}): RenderInputsIndexEntry | undefined;
+/**
+ * Every manifest in the store, sorted by `renderedAt` then `contentDigest`
+ * for a stable listing. Entries whose manifest is missing or unreadable are
+ * skipped — a listing never fails on one corrupt entry. This is the query
+ * surface the diff issues (#1249/#1250) resolve digests against.
+ */
+export declare function listRenderManifests(opts?: {
+    root?: string;
+}): RenderManifest[];
+/** How a caller names one document inside a stored render. */
+export interface RenderDocumentRef {
+    kind: string;
+    name: string;
+    /** Omit (or pass `null`) to match a cluster-scoped / namespace-less document. */
+    namespace?: string | null;
+}
+/**
+ * Resolve one document by kind/namespace/name to its exact bytes inside a
+ * stored render, via the manifest's document index. The slice is verified
+ * against the entry's per-document digest before being returned — corrupt
+ * content is an error, never silently wrong bytes. `undefined` means the
+ * store has no such render or the index has no such document.
+ */
+export declare function readRenderDocument(contentDigest: string, ref: RenderDocumentRef, opts?: {
+    root?: string;
+}): {
+    entry: RenderDocumentEntry;
+    text: string;
+} | undefined;
+//# sourceMappingURL=render-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render-store.d.ts","sourceRoot":"","sources":["../src/render-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAYH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAIlD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gFAAgF;IAChF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,kGAAkG;IAClG,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,iGAAiG;IACjG,OAAO,EAAE,CAAC,CAAC;IACX,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,mDAAmD;IACnD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,iIAAiI;IACjI,iBAAiB,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACnF,yGAAyG;IACzG,aAAa,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,QAAQ,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;;;OAMG;IACH,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,IAAI,CAAC;CAClD;AAED,uFAAuF;AACvF,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,CAAC,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAsBD,qEAAqE;AACrE,MAAM,WAAW,oBAAoB;IACnC,gIAAgI;IAChI,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4HAA4H;IAC5H,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,iBAAiB,EAAE,qBAAqB,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAcnE;AAaD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAEzE;AAkFD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,mBAAmB,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAyB9G;AAID,MAAM,WAAW,sBAAsB;IACrC,4GAA4G;IAC5G,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IAC1C,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,uFAAuF;IACvF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3C,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,uFAAuF;IACvF,QAAQ,EAAE,cAAc,CAAC;IACzB,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,mBAAmB,CA0EpF;AAID,gHAAgH;AAChH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,GAAG,SAAS,CAS9G;AAED,mGAAmG;AACnG,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CAKrG;AAED,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACvB,sBAAsB,GAAG,SAAS,CAOpC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,EAAE,CAmB9E;AAED,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,iBAAiB,EACtB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACvB;IAAE,KAAK,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAoB1D"}

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"}