@intentius/chant-lexicon-helm 0.46.0 → 0.50.0

package/dist/render-diff.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Render diffing (#1249 offline, #1250 live — epic #1228 Phase 6), the two
+ * halves of `chant helm diff` (./commands.ts).
+ *
+ * `diffRenders` (#1249) is the offline half: given two content digests
+ * already in the render store (render-store.ts), report what changed
+ * between them — no cluster, no credentials, no live read. This is the
+ * pre-flight question a pin, a chart bump, or a values change all raise:
+ * "what will this touch?"
+ *
+ * Pairing is document-level, keyed on `(kind, namespace, name)` — the same
+ * identity `RenderManifest.documents` already indexes (render-store.ts).
+ * That index exists precisely so two renders can be matched without
+ * reparsing a whole stream: a document present on both sides with the same
+ * per-document digest is unchanged and costs nothing further; one whose
+ * digest differs is parsed on both sides and diffed field by field.
+ *
+ * Field-level diffing reuses core's `flattenDeepProperties` /
+ * `deepValueEqual` (packages/core/src/deep-observation.ts) — the same
+ * path-flattening core's own live-drift diff (lifecycle/deep-diff.ts) is
+ * built on. This module does not reuse `diffDeep` itself for the offline
+ * path: that function's shape is declared/live/baseline/fieldOwners,
+ * tailored to a source tree vs a cluster read. A stored render has neither
+ * a baseline nor a field owner, and both sides here are equally "declared"
+ * — reusing the flatten/compare primitives without the three-way apparatus
+ * is the right cut for render-to-render.
+ *
+ * Duplicate documents (an aliased dependency emitting the same CRD twice,
+ * render-digest.ts's canonicalization note) are matched positionally within
+ * their `(kind, namespace, name)` group: first occurrence to first, second
+ * to second. A group with more entries on one side reports the surplus as
+ * added or removed rather than guessing which duplicate corresponds to
+ * which.
+ *
+ * A document neither side's manifest could index (unparseable, or missing
+ * `kind`/`metadata.name` — render-store.ts's `indexRenderDocuments`) cannot
+ * be paired by identity. It is never silently dropped: `unindexed` counts
+ * it on whichever side(s) it appears, so a diff over two renders that both
+ * carry unindexable documents does not quietly under-report.
+ *
+ * `diffRenderLive` (#1250) is the online complement: given a single
+ * `contentDigest` resolved from the render store, read the live property
+ * tree for every document the render recorded — by identity
+ * (kind/namespace/name), not by helm release — and diff each one against
+ * the render's own stored bytes with `lifecycle/deep-diff.ts`. This *does*
+ * reuse `diffDeep`'s three-way apparatus (via `diffDeepObservation`): the
+ * declared side is the render's stored documents, the live side is a
+ * cluster read, which is exactly that function's shape.
+ *
+ * The declared side for the live path is the render's stored documents,
+ * never a fresh `helm template` run and never a chant TS build. A digest
+ * not in the store — an unpinned render was never persisted
+ * (`render-store.ts`'s `persistHelmRender` refuses that) — has nothing to
+ * diff against and comes back `found: false`, never a false "no drift" over
+ * documents nobody has (epic AC: unpinned releases handled without false
+ * drift).
+ *
+ * The live side reuses the exact seam `observeResourcesDeepHelm` (#1247)
+ * uses — the k8s lexicon's typed client and normalization hooks — so a
+ * document this reads and one a release's `describeResources` reads compare
+ * under the same rules (secret masking, managed-fields ownership, pruning).
+ * Hook resources need no special handling here the way the release-scoped
+ * read needs a second `helm get hooks` channel: `helm template` (what
+ * produced the stored render) already includes hook manifests as ordinary
+ * documents, so they are simply rows in `manifest.documents` like any other.
+ */
+import type { DeepDiffResult } from "@intentius/chant/lifecycle/deep-diff";
+import type { K8sConnector } from "@intentius/chant-lexicon-k8s/api/connect";
+import { type RenderManifest } from "./render-store.js";
+/** How one field within a changed document differs between the two renders. */
+export interface RenderFieldChange {
+    /** Path within the document's property tree (`spec.replicas`, `data.zeta`). */
+    path: string;
+    /**
+     * `changed` — both renders have the path, with different values.
+     * `added` — only the right-hand (`to`) render has it.
+     * `removed` — only the left-hand (`from`) render has it.
+     */
+    kind: "changed" | "added" | "removed";
+    /** Value on the `from` side. Absent for `added`. */
+    before?: unknown;
+    /** Value on the `to` side. Absent for `removed`. */
+    after?: unknown;
+}
+/** Identity of one document, for reporting — the same triple documents are paired on. */
+export interface RenderDiffDocumentRef {
+    kind: string;
+    namespace: string | null;
+    name: string;
+    /** The `# Source:` origin path, when the document carried one. */
+    source: string | null;
+}
+/** A document present on only one side. */
+export interface AddedOrRemovedDocument extends RenderDiffDocumentRef {
+    digest: string;
+}
+/** A document present on both sides with different content. */
+export interface ChangedDocument extends RenderDiffDocumentRef {
+    /** Per-document digest on the `from` side. */
+    beforeDigest: string;
+    /** Per-document digest on the `to` side. */
+    afterDigest: string;
+    /** Field-level differences, sorted by path. Empty only if a document parses but yields no leaves. */
+    changes: RenderFieldChange[];
+}
+export interface RenderDiffResult {
+    from: {
+        contentDigest: string;
+        chart: string;
+        releaseName: string;
+    };
+    to: {
+        contentDigest: string;
+        chart: string;
+        releaseName: string;
+    };
+    /** Present only on `to`. Sorted by kind/namespace/name. */
+    added: AddedOrRemovedDocument[];
+    /** Present only on `from`. Sorted by kind/namespace/name. */
+    removed: AddedOrRemovedDocument[];
+    /** Present on both, different bytes. Sorted by kind/namespace/name. */
+    changed: ChangedDocument[];
+    /** Present on both with equal per-document digest — reported as identities only, no field pass run. */
+    unchanged: RenderDiffDocumentRef[];
+    /**
+     * Documents each manifest's index could not identify — present in the
+     * stream (`docCount`) but absent from `documents` (unparseable, or no
+     * `kind` + `metadata.name`). Never matched, never silently dropped.
+     */
+    unindexed: {
+        from: number;
+        to: number;
+    };
+}
+export interface DiffRendersOptions {
+    /** Render store root override; defaults to `renderStoreRoot()`. */
+    root?: string;
+}
+/**
+ * Diff two renders already in the store, by content digest. Offline: every
+ * byte compared comes from the archive (render-store.ts), never a cluster.
+ *
+ * Throws when either digest has no manifest — a diff over a render nobody
+ * persisted is a usage error, not an empty report.
+ */
+export declare function diffRenders(from: string, to: string, options?: DiffRendersOptions): RenderDiffResult;
+/** True when the diff found no added, removed, or changed documents. */
+export declare function renderDiffIsEmpty(result: RenderDiffResult): boolean;
+export interface RenderLiveDiffOptions {
+    /** The stored render to diff against the cluster — a `contentDigest` from `chant helm renders`. */
+    contentDigest: string;
+    /** The chant environment the live read targets — resolves the k8s cluster binding (`k8s.profiles.<environment>.context`), same as any other live read. */
+    environment: string;
+    /** Render store root override (tests); defaults to `renderStoreRoot()`. */
+    root?: string;
+    owned?: boolean;
+}
+export interface RenderLiveDiffDeps {
+    /** Forwarded to the k8s reader — a test passes a fake cluster's connector. */
+    connect?: K8sConnector;
+}
+export type RenderLiveDiffOutcome = {
+    found: true;
+    manifest: RenderManifest;
+    diff: DeepDiffResult;
+}
+/** No such render in the store — refuse the diff rather than report a false clean result. */
+ | {
+    found: false;
+    contentDigest: string;
+};
+/** Row key convention shared with the release-scoped reads (#1246/#1247): `<Kind>/<namespace>/<name>`, `cluster:<Kind>/<name>`. */
+export declare function documentKey(kind: string, namespace: string | undefined, name: string): string;
+/**
+ * A namespace-silent document defaults to the render's target namespace —
+ * the same rule a deployed release applies to its manifest (`helm apply
+ * -n <ns>` targets whatever a namespace-silent object's `.Release.Namespace`
+ * would have filled in) — unless the kind is cluster-scoped, in which case a
+ * missing namespace is never defaulted.
+ */
+export declare function resolveDocumentNamespace(kind: string, declared: string | null, renderNamespace: string | null): string | undefined;
+/**
+ * Diff one stored render's documents against the live cluster.
+ *
+ * `found: false` when `contentDigest` is not in the store — never fabricates
+ * a document, and never reports "no drift" over a render this has no bytes
+ * for. On a found render, every document indexed in its manifest becomes a
+ * synthetic declared entity (keyed like a release's rows), read live through
+ * the k8s lexicon's deep observer, and diffed property-by-property.
+ */
+export declare function diffRenderLive(options: RenderLiveDiffOptions, deps?: RenderLiveDiffDeps): Promise<RenderLiveDiffOutcome>;
+//# sourceMappingURL=render-diff.d.ts.map

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

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

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