Chart to Recipe to Manifest Flow

This note describes the proposed ConfigHub/cub installer flow for Helm-derived packages, where every source of new information is made explicit and every risky Helm feature is handled at the right stage.

Mission

The Helm mission is to remove as much Helm pain as possible by moving hidden rendering, variation, review, delivery, and observation concerns into explicit ConfigHub artifacts and receipts.

That does not mean "never use Helm". It means Helm stops being the only place where the user has to reason about hidden state, invisible generator behavior, values-file guesswork, and fragile one-off deployment scripts.

The promise:

Use the Helm ecosystem.
Import once.
Vary freely.
Review the exact Kubernetes objects.
Scan every important variant.
Deploy approved revisions without re-rendering and hoping.
Keep receipts for what changed, who approved it, what was applied, and what external observers saw live.

The 60-second story:

Helm generates Kubernetes objects. ConfigHub captures those objects as
immutable variant revisions. You approve the exact rendered objects, scan them
before install, promote the same revision to prod, see why environments differ,
and get receipts proving what changed and what was observed.

Use Helm charts. Ship ConfigHub variants.

From the attached "first two problems" note, the product should directly answer these user pains:

• "I do not want to approve a values file and hope. I want to approve the exact Kubernetes objects that will be applied."
• "I deployed the same thing to prod and got something subtly different. I have no idea why."
• "I need the thing we tested in staging to be the exact thing we promote to prod, not a generator we rerun and hope produces the same output."
• "Our vendor pushed a chart upgrade. Half my customisations still work, half conflict."
• "SecOps patched the base image. I need to roll it across 12 customer environments without breaking any of them."
• "I can't tell what changed, what landed, or whether prod saw the same thing dev approved."

So the mission is not just deterministic import. The mission is a managed variant family:

managed variants
+ tracked operations
+ signed receipts
+ exact rendered artifacts
+ bulk checks
+ day-2 propagation
= less hidden Helm pain, with explicit blockers where automation is unsafe

Variants Are the Product Spine

The ConfigHub variants model should be the center of the Helm story.

Helm's native unit is a chart release. Git's native unit is a file change. Argo CD and Flux mainly operate desired-state sources and sync status. None of those is quite the object the user cares about when they say:

dev, staging, prod, EU, Customer A, GPU region, HA mode, TLS mode

Those are variants.

In the new flow:

recipe
  -> variant
  -> variant revision
  -> rendered manifest set
  -> scan results
  -> install/operate receipts

Definitions:

• Recipe: the reusable source model imported from Helm/Kustomize/raw manifests/etc.
• Variant: a named desired-state member of the family, such as prod-eu, customer-a, ha-tls, or gke-gpu.
• Variant revision: an immutable approved version of that variant, with values, overlays, facts, capability profile, generated facts, and rendered manifests fixed.
• Operation: an action against one or more variant revisions: install, promote, deploy, remediate, rollback, rescan, reobserve.
• Receipt: evidence for the operation or observation: inputs, outputs, authority, target, result, observer, and freshness.

This is the user promise:

You do not manage piles of Helm values files.
You manage a family of variants.
Each variant has approved revisions.
Each revision has exact rendered objects and receipts.

A variant is only real if it carries enough state to be approved, promoted, compared, scanned, and operated. A values file with a nicer label is not a complete variant.

A ConfigHub variant revision must include:

• Recipe inputs.
• Environment and target fact values used during render, satisfying the target fact requirements declared by the recipe.
• Capability profile.
• Generated facts or generated secret handles.
• Rendered release objects.
• Immutable revision identity.
• Diff from another variant or revision.
• Scan and gate result.
• Operation and observation receipts.

Five Objections, Five Answers

The answer must be:

Less Helm pain. Not more platform ceremony.

1. "Is this another abstraction on top of Helm?"

No. Helm remains the chart ecosystem. ConfigHub adds the missing managed object:

Use Helm charts.
Ship ConfigHub variants.

ConfigHub is not a new templating religion. It is a variant manager, receipt layer, and operation record.

2. "Will this work with my real charts?"

The first job is to explain the chart before install:

OK: values, dependencies, CRDs
Needs facts: lookup Secret redis-password
Needs policy: pre-install hook
Blocked: unpinned post-renderer

That is already better than Helm failing late, silently ignoring values, or hiding behavior inside render-time side effects.

3. "Is this too much process for small teams?"

The simple path stays simple:

install
review/plan
publish

Receipts, scans, and variant records are produced automatically. Teams can add approvals, variant matrices, initiatives, and promotion workflows when they need them.

4. "Who owns truth: Git, Helm, Argo, Flux, the cluster, or ConfigHub?"

Each keeps its job:

Helm supplies charts.
Git stores files.
Argo/Flux sync clusters.
ConfigHub records variants, operations, and proof.
cub-scout, GitOps, CI, and other external observers report live state.

ConfigHub is the operational system of record. It can emit Git, OCI, YAML, or GitOps inputs instead of replacing delivery tools.

5. "What happens when YAML needs to change?"

Change the variant. Do not guess through values files.

Helm: change values, hope the path works, rerender, compare noise.
ConfigHub: change variant, see affected fields, scan exact output, promote approved revision.

The crisp headline:

Helm gives you charts.
ConfigHub gives you managed, reviewable, scannable, promotable variants from those charts.

User-facing naming should stay simple:

Keep the heavier terms in schemas and technical docs. Do not put them in the headline.

Core flow:

Helm chart source
  -> Helm Recipe Import
  -> ConfigHub Install Variants
  -> immutable variant revisions
  -> environment facts used during render
  -> Rendered Release Objects
  -> scan exact objects before install
  -> Verified Install Gate
  -> ConfigHub operate/day-2 lifecycle

The important product claim is not "ConfigHub scans Helm charts once". It is:

ConfigHub makes Helm's possible install outputs explicit, reproducible, attributable, and scannable.

The user-facing version is:

With cub, Helm becomes an input format. The thing you approve, scan, promote, roll back, and operate is an addressable ConfigHub variant revision with receipts.

Build on confighub/installer

This plan should be built on confighub/installer, not as a separate Helm system.

Installer already has much of the substrate:

• cub installer plugin entrypoint.
• Package authoring with installer.yaml.
• Kustomize bases and components.
• Inputs, selection, and deterministic out/spec/ state.
• Collector-produced facts.yaml.
• ConfigHub function chains and validators.
• Dependency resolution and lock files.
• Deterministic package bundling.
• OCI push/pull/inspect/list/tag.
• Cosign sign/verify and trust policy.
• Render/upload/day-2 lifecycle.

The Helm work should add the missing layer:

• Helm Recipe Import from chart source into installer package/recipe structure.
• Source/dependency locks for Helm chart closure.
• Import diagnostics and control-point classification.
• ConfigHub Install Variant definitions.
• Immutable variant revision receipts.
• Recipe-declared target fact requirements plus capability/generated fact profiles for Helm-specific nondeterminism.
• Rendered Release Object receipts.
• Scan/gate receipts.
• External observation receipt integration for cub-scout, GitOps, CI/CD, and other observers.

So the implementation claim is:

Extend confighub/installer so Helm charts become ConfigHub installer recipes
and managed variant revisions.

Execution Surfaces

Every step in the plan must be executable through one or more of:

• cub CLI / cub installer, backed by confighub/installer.
• ConfigHub Server UI/API for stored variants, variant revisions, receipts, target assignments, approvals, initiatives, desired state, and the OCI endpoint used by the fast install path.
• cub-scout, GitOps controllers, CI/CD, or other external observers for live observation receipts.

The current proof is not trying to execute a pure serverless install path. GitHub is the public catalog/proof surface, currently confighub/helm-expt. The fast install path uses ConfigHub's OCI endpoint. A fully client-side, serverless cub installer path is a deferred option and should be tracked as an issue, not treated as part of the current proof.

Backlog gates are tracked in docs/planning/issue-backlog.md. Any open P0 issues in that file must not be bypassed by the flow; they are gates for the scope they name.

The consolidated doctrine and historical execution record is in docs/planning/agreed-execution-plan.md. Current command routing lives in docs/user/choosing-commands.md; the npm proof-command map lives in tests/npm-scripts.md. Treat the shorthand below as candidate product porcelain unless one of those command maps names it as a current command. During implementation, every durable chart input, recipe, variant, revision, scan, gate, publish/apply action, and observation must map back to a real execution surface and produce an addressable artifact or receipt.

The upstream installer docs usually write these as installer ... commands. Here they are written as cub installer ... because the installer is used through the Cub plugin.

Target happy path:

install redis
review/plan redis
publish redis

The first command should quietly:

resolve the Helm chart
create or update the Redis recipe candidate
create the default install variant
render an immutable variant revision
scan the exact rendered objects
prepare a Verified Install Gate
write receipts

The publish command should publish the approved revision through ConfigHub's OCI endpoint for GitOps pickup and write an OCI artifact receipt. Direct apply can exist for local kind tests or explicit customer choice, but it is not the default public handoff.

Easy variant path:

create redis HA variant
review/plan redis HA against default
publish approved HA revision

or:

create redis reuse-existing-secret variant
bind redis-password fact or secret handle
publish approved reuse-existing-secret revision

Implementation may initially expose more explicit cub installer ... subcommands while this is being built, but the product proof should aim at the simple UX above. The machinery is allowed to exist; it should not be the happy path.

Workerless Server Boundary

ConfigHub Server should not be described as having a built-in live view if the direction is workerless.

The server's job is to store and govern:

• Recipes.
• Variants.
• Variant revisions.
• Rendered manifest identities.
• Scan results.
• Operation records.
• Receipts.
• Target assignments and desired state.

Live observations come from outside the server:

• cub-scout.
• GitOps controller reports.
• CI/CD jobs.
• Customer-owned agents or integrations.
• Human-triggered cub observations.

So the state model is:

intended state
  stored by ConfigHub Server

applied state
  recorded by operation receipts from cub, GitOps, CI/CD, etc.

live observation
  submitted as observation receipts by cub-scout, GitOps, CI/CD, or other external observers

ConfigHub Server can aggregate and display intended/applied/observed state, but it should not be the thing that directly watches every cluster unless a customer explicitly deploys an observer that reports back.

Hard rule:

ConfigHub stores desired/config truth and submitted observation receipts.
It does not claim fresh runtime truth unless a current receipt says so.

The UI must show freshness plainly:

Observed by cub-scout 4m ago.
Argo report 17m old.
No runtime receipt yet.

1. The New Flow

Step 0: Source Selection

Input:

• Helm repository URL or OCI registry reference.
• Chart name and version.
• Optional provenance/signature.
• Expected chart archive digest.

Output:

• A pinned chart source identity:

chartRef + version + chartArchiveSHA256 + acquisition metadata

Checks:

• Refuse mutable "latest" style imports unless resolved to a digest.
• Record the exact archive hash.
• Record repository URL and transport.
• Prefer signed/provenance-checked charts where available.
• Treat unavailable or malformed archives as a pre-recipe blocker.

This is where the five failed rows in the top-500 scan belong. They are not Helm semantics problems; they are source-acquisition failures.

Step 1: Dependency Closure

Helm input points:

• Chart.yaml dependencies.
• Chart.lock.
• Vendored charts/*.tgz.
• Unpacked subcharts.
• Umbrella charts.
• Library charts.
• Remote dependency repositories.
• Version constraints.

Output:

• A dependency lock for the entire chart closure:

root chart digest
+ every dependency name/version/digest
+ importer dependency policy
= helm-source-lock

Checks:

• Never run helm dependency update implicitly during import.
• Require Chart.lock, vendored subcharts, exact dependency digests, or a first-class dependency resolution receipt.
• Record library charts even though they do not render resources directly.
• Treat umbrella charts as dependency graphs, not as special cases.

If dependency resolution is needed, it is its own auditable step. It is not hidden inside chart-to-recipe import.

Step 2: Recipe Import

Input:

• Pinned chart source.
• Dependency lock.
• Importer version.
• Import policy version.

Output:

• One canonical ConfigHub recipe for the chart source.
• Recipe-declared target fact requirements for any lookup or cluster-sourced render dependency.

Recommended framing:

1 Helm chart source -> 1 recipe -> N ConfigHub variants -> M variant revisions

Only split into multiple recipes when the source package is intentionally forked or the importer policy creates materially different package semantics. Normal HA/default/TLS/cloud/environment/customer differences should be variants and variant revisions, not separate recipes.

Checks:

• The importer must be deterministic from source bytes plus policy bytes.
• Import must not contact the target cluster.
• Import must not execute hooks.
• Import must not perform live lookup.
• Import must not generate random values.
• Any unsupported Helm behavior becomes an explicit recipe diagnostic.

There are two acceptable import modes:

• Symbolic recipe mode: compile chart structure into recipe inputs, target fact requirements, components, function chains, and render rules.
• Render-and-vendor mode: render one or more explicit variants and wrap those rendered artifacts. This is easier, but the Helm render context must be captured as a receipt.

The stronger long-term story is symbolic recipe mode. Render-and-vendor remains useful for compatibility and experiments.

Step 3: Recipe Validation

Input:

• Imported recipe.
• Extracted value schema.
• Import diagnostics.

Output:

• A recipe that can either be rendered safely or rejected early.

Checks:

• Validate recipe schema.
• Validate mapped inputs.
• Convert Helm required and fail into recipe validation rules where possible.
• Flag unbounded tpl, raw manifest injection, unsupported hook behavior, or missing fact declarations.
• Confirm no unresolved source dependencies remain.

This is where ConfigHub-specific malformed package checks start. Market tools generally cannot inspect this layer because it is not Kubernetes YAML yet.

Step 4: Variant Definition

Input:

• Recipe.
• Curated variant catalog.
• Organization policy.

Output:

• A bounded set of named ConfigHub variants:

default
ha
ha-with-persistence
tls-enabled
ingress-enabled
restricted-security-context
fresh-install
reuse-existing-secret
k8s-1.29
k8s-1.30
eks
gke
aks

Checks:

• Do not attempt every possible Helm values combination.
• Define market-relevant and organization-relevant base variants.
• Make each variant's values, selected components, overlays, capability profile, and target/generated fact value profile explicit. Target fact requirements come from the recipe.
• Require each variant to have a stable identity and digest.
• Record parent/child relationships between variants when one derives from another.
• Make local deltas explicit, so base updates can be propagated or flagged for review.

Variants are the bridge between Helm flexibility and ConfigHub auditability.

Step 4b: Variant Revision

Input:

• Variant definition.
• Base recipe version.
• Values profile.
• Selected overlays/components.
• Target/generated fact value profiles and capability profiles.
• Approval state.

Output:

• An immutable variant revision.

Checks:

• Once approved, a variant revision is not re-rendered implicitly.
• Promotion deploys the approved revision, not a generator invocation.
• New source, values, fact values, policy, or scanner changes create a new candidate revision.
• Revisions can be compared by source, values, facts, rendered manifests, scan results, and target state.

Step 5: Target Fact Values, Capability Profiles, and Generated Facts

Input:

• Variant.
• Recipe-declared target fact requirements.
• Target cluster snapshot, when rendering for a real target.
• Synthetic fact value profiles, when bulk scanning representative scenarios.

Output:

• Captured fact value profiles:

values-profile@sha
capability-profile@sha
target-facts@sha
generated-facts@sha

Checks:

• Cluster state is only observed during fact collection.
• Render must not perform hidden live-cluster reads.
• Same recipe + same values + same capability profile + same target/generated fact values must produce byte-identical manifests.
• Sensitive values should not be stored as plain facts; store references, generated secret handles, or secret material in the existing secret path.

This is how we handle Helm lookup: turn cluster-sourced nondeterminism into target fact requirements in the recipe, then bind captured target fact values when rendering a variant revision.

Example:

Helm source:
  lookup Secret redis-password

Recipe:
  requires target fact redisPasswordSecret.exists

Variant A:
  redisPasswordSecret.exists = false

Variant B:
  redisPasswordSecret.exists = true

Now both outcomes are renderable, scannable, and repeatable.

This aligns with the current installer direction: installer already has a collector extension point that writes out/spec/facts.yaml, and render uses .Facts.* from that captured file. The Helm import plan generalizes that mechanism into recipe-declared target fact requirements, capability profiles, and generated facts for variant revisions.

Step 6: Render

Input:

• Recipe digest.
• Variant digest.
• Values profile.
• Capability profile.
• Target fact values satisfying the recipe's target fact requirements.
• Generated facts.
• Dependency lock.
• Renderer version.
• Helm render parameters, if Helm rendering remains part of the path: release name, namespace, kube version, API versions, include CRDs, install versus upgrade phase, and test inclusion.

Output:

• A concrete rendered manifest set:

renderedManifestSet@sha

Checks:

• Run two-render determinism checks for the same inputs.
• Store manifest digest.
• Canonicalize rendered manifests before digesting: parse YAML documents, normalize to canonical JSON with sorted object keys, keep list order, remove empty documents, and preserve Kubernetes object identity as apiVersion|kind|namespace|name.
• Store render command/options.
• Store tool versions.
• Separate normal manifests, secrets, CRDs, hooks, and tests where useful.
• Block render if required facts are missing.
• If Helm's post-renderer mechanism is supported, represent it as a named, pinned recipe/function stage. Otherwise reject it.

This is the point where standard Kubernetes policy scanners become most useful, because the output is actual Kubernetes YAML.

Expected digest formula for proof artifacts:

variantRevision.digest =
  sha256(
    recipe.digest,
    effectiveValues.digest,
    capabilityProfile.digest,
    factBindings.digest,
    generatedFacts.digest,
    renderer.digest,
    renderedManifestSet.digest
  )

helm-expt defines and verifies this contract. confighub/installer may later emit native receipts, but installer implementation is an upstream dependency, not code owned by this repo.

Step 7: Kustomize, Overlays, and ConfigHub Functions

Kustomize can appear in several places:

• As the implementation substrate of an installer package.
• As a wrapper around Helm-rendered output.
• As bases selected by recipe variants.
• As components selected by recipe variants.
• As overlays or patches.
• As images, replicas, namespace, name prefix/suffix, replacements, ConfigMap generators, Secret generators, and transformers.

ConfigHub functions can also appear here:

• Normalizing labels and annotations.
• Setting namespace.
• Setting container images/resources.
• Applying security defaults.
• Validating or mutating resources.
• Splitting rendered output into ConfigHub Units.

Checks:

• Kustomize remote bases must be pinned or vendored.
• Generators must have stable input files and stable generator options.
• Secret generator material must be treated as generated/secret facts, not as hidden source.
• Components and overlays must be named variant inputs.
• ConfigHub function chains must be resolved from recipe inputs/facts and written to the render receipt.
• No post-render mutation should be invisible; every overlay/function/policy bundle gets a digest.

Kustomize is not a loophole around receipts. It is another explicit stage in the same recipe-to-manifest pipeline.

Step 8: Bulk Policy and Misconfiguration Scans

Input:

• Rendered manifest sets.
• Scanner versions.
• Policy bundle versions.

Output:

• Scan result per manifest set:

renderedManifestSet@sha
+ scanner@version
+ policyBundle@sha
= scanResult@sha

Examples:

• Snyk IaC.
• Trivy config scanning.
• Checkov.
• Kubescape.
• kube-linter.
• kubeconform/kubeval.
• OPA/Conftest.
• ConfigHub scan.
• Custom initiative functions.

Checks:

• Scan concrete manifests, not just abstract chart source.
• Store scanner version and policy database/bundle digest.
• Treat each variant independently.
• Treat each variant revision immutably.
• Aggregate results across variants for initiatives.
• Gate install on the exact variant being installed.

The atomic audit object should be per renderedManifestSet@sha. A higher-level initiative result should roll up many manifest-set scan results.

Step 9: Install Gate and Receipt

Input:

• Rendered manifest set.
• Variant revision.
• Scan results.
• Import/render receipts.
• Organization policy.

Output:

• Approved or blocked install plan.

Checks:

• Confirm the selected variant revision is the one scanned.
• Confirm scan results are fresh enough for policy.
• Confirm source, recipe, facts, generated facts, overlays, and manifest digests are all linked.
• Confirm signatures/trust policy where required.
• Refuse install if the render cannot be traced back to source and policy.

Step 10: Operate and Day-2 Lifecycle

Input:

• Installed ConfigHub Units.
• Variant revisions.
• Installer record.
• Prior receipts.
• New target fact values.
• Observation receipts from cub-scout, GitOps controllers, CI/CD, or other external observers.
• User edits.
• Drift.

Output:

• Reconcile, upgrade, or re-render plan.

Checks:

• Re-rendering with the same spec and facts should be byte-identical.
• If target fact values change, create a new render context rather than silently changing output.
• Preserve post-install ConfigHub edits according to merge policy.
• Re-run scans when manifests, policies, scanner versions, or relevant facts change.
• Track observed live drift separately from source/render determinism.
• Mark observed state stale when no fresh external observation receipt exists.
• Manage promotion, rollback, and remediation against variant revisions, not loose files.

2. Every Entry Point for New Information

3. Checks by Failure Type

4. How This Solves the First Two Problems

Problem 1: Install Config Correctly

The current pain is that users approve abstract inputs and hope the generated output is correct. The new flow changes the review object.

Old flow:

approve values.yaml
run helm somewhere
hope the cluster got what was intended

New flow:

create/update variant
render candidate variant revision
approve variant revision
review exact rendered YAML
scan exact rendered YAML
install exact approved manifest set
record receipt

Controls:

• Values that do not apply without warning become recipe validation and dead-key checks.
• Non-deterministic re-renders become recipe-declared target fact requirements, bound target fact values, generated facts, capability profiles, and two-render determinism checks.
• Helm CLI versus Argo CD versus Flux render differences become explicit renderer/toolchain receipts.
• "Which value set this field?" becomes recipe/variant provenance.
• "What will be deployed?" becomes renderedManifestSet@sha.
• "What did we approve?" becomes variantRevision@sha.

Problem 1b: Small-Scale Helm Pain

Even small teams see the same failure modes:

• Wrong values path.
• Merge conflicts between Helm and GitOps controllers.
• Random secrets and timestamps.
• CRD upgrade gaps.
• Controller-injected diff noise.
• Missing resource requests, HPA settings, topology spread, and other reliability defaults.

In the new flow, these are not all solved by one scanner. They are solved at different points:

• Wrong values path: recipe validation and values schema checks.
• Merge conflicts: ConfigHub ownership and operate policy.
• Random secrets/timestamps: generated facts.
• CRD gaps: CRD phase and schema/upgrade policy.
• Diff noise: intended/applied/observed-live views are separated, with observed-live data supplied by cub-scout, GitOps, CI/CD, or other external observers.
• Reliability defaults: bulk policy scans over concrete manifest variants.

Problem 2: Manage Related Variants Over Time

The server-side version of the plan is about managing a family of related approved states, not re-running generators whenever a target changes.

Old flow:

many values files
+ many clusters
+ custom scripts
+ GitOps sync events
= no durable variant/operation record

New flow:

base recipe update
  -> affected variants
  -> candidate variant revisions
  -> render and scan each candidate revision
  -> approve exact variant revisions
  -> promote/deploy those approved revisions to targets
  -> record operation receipts
  -> ingest external observation receipts for live freshness

Controls:

• Promotion is not a copy; it advances one variant from one approved revision to another while preserving prod/customer constraints.
• Rollback is variant-relative; it moves a variant/target back to a prior approved revision without reverting unrelated variants.
• Base updates are propagated through explicit variant deltas.
• Operations are first-class records, not just commits or sync events.
• Operation receipts include authority, target, artifact, and result.
• Observation receipts include observer, method, timestamp, and freshness.

This is why "deploy and vary however much you like" is plausible: variation happens in the ConfigHub variants model, and deployment operates approved variant revisions.

5. Legacy Top-500 Source Scan

The existing workbook scan is legacy/reference material. It covered 500 Artifact Hub Helm packages sorted by stars and statically scanned chart source; it did not execute templates, hooks, or lookups.

Do not treat the existing workbook as the current proof pathway. The current plan requires new chart proof repos and new generated spreadsheets backed by recipe, variant, revision, scan, gate, and receipt artifacts.

The chart count alone proves nothing. The evidence matters only if each chart can be connected to real recipe candidates, bounded install variants, rendered objects, scan results, gates, and failure classifications.

The new top-20/top-100/top-500 proof should show breadth across complex Helm reality:

• CRDs.
• Hooks.
• Dependencies.
• Globals.
• Values schemas.
• Cloud-specific knobs.
• Generated names and generated secrets/certs.
• SecurityContext and policy drift.
• Image override patterns.
• Ingress and TLS variants.
• Upgrade/customization conflicts.

Legacy scan summary:

Feature counts among scanned charts:

Important overlaps:

Conclusion from the legacy scan:

The top-500 chart features do not defeat the plan.
They force the plan to be explicit.

Every observed feature class has a control:

• Lock and verify source/dependencies.
• Convert cluster reads into recipe-declared target fact requirements and bound target fact values.
• Convert random/time/cert generation into generated facts.
• Convert required/fail into input validation.
• Convert capabilities into named capability profiles.
• Convert install/upgrade branching into render phase variants.
• Convert hooks into lifecycle phases/tests or fail early.
• Convert raw/tpl escape hatches into explicit extension slots or reject them.
• Scan concrete manifest sets for Kubernetes policy and misconfiguration.

The system cannot make an unavailable chart archive available. It should block or require mirroring. It also cannot prove semantic safety from a static regex scan alone. The importer must eventually use a proper chart/template parser and record importer diagnostics.

6. Bulk Policy, Scan, and Misconfiguration Checks

The bulk-scanning model still works:

recipe@sha
  variant: default
    revision: default@2026-05-25.1
    renderedManifestSet@sha -> Snyk/Trivy/Checkov/Kubescape/ConfigHub scan
  variant: ha
    revision: ha@2026-05-25.1
    renderedManifestSet@sha -> Snyk/Trivy/Checkov/Kubescape/ConfigHub scan
  variant: tls-enabled
    revision: tls-enabled@2026-05-25.1
    renderedManifestSet@sha -> Snyk/Trivy/Checkov/Kubescape/ConfigHub scan

There should be two result levels:

• Atomic result: scanner result for one renderedManifestSet@sha and one policy bundle.
• Variant revision result: aggregate over all scans/checks for one immutable variant revision.
• Initiative result: aggregate over many variants, revisions, charts, targets, and scanners.

This lets ConfigHub answer both questions:

• "Is this exact variant revision safe to publish or apply?"
• "How healthy is our Redis/Ingress/Monitoring initiative across all standard variants?"

Market scanners belong mostly after render. ConfigHub scan belongs both before and after render:

• Before render: recipe validity, missing fact values, unsupported lookup, unbounded tpl, unsafe generated fact handling, invalid variant definitions.
• After render: Kubernetes object validity, policy violations, image/security checks, RBAC, CRDs, webhooks, storage, network exposure.

7. Leftover Design Questions

These are not optional details. They are the remaining defaults that turn the plan into a product.

Top Target Facts

Likely top target fact requirements Helm recipes need:

1. Kubernetes version.
2. Available API versions and CRDs.
3. Target namespace exists, plus labels/annotations when charts branch on them.
4. Named Secret exists and required keys exist.
5. Named ConfigMap exists and required keys exist.
6. Existing CRD ownership and served versions.
7. StorageClass/default storage class/volume expansion support.
8. IngressClass or GatewayClass availability/defaults.
9. Existing ServiceAccount/RBAC objects when charts support reuse.
10. Certificate issuer or TLS secret availability.
11. ImagePullSecret availability.
12. Existing PVC availability for stateful reuse/upgrade flows.

The first two are closer to capability profiles than ordinary facts, but users will think of them as target facts. The UI can group them while keeping the receipt model precise. The recipe declares these requirements; a render context or variant revision binds the concrete target fact values.

Lookup Default

Recommended policy:

• Strict import: lookup must map to a declared target fact requirement or import fails.
• Bulk scan: render synthetic variants for common fact values.
• Real install: run a collector once, store target fact values, render from the stored snapshot.

Do not allow hidden live lookup during render.

Variant-Specific vs Recipe-Wide Misconfigs

Recipe-wide:

• Unsupported Helm functions.
• Unlocked dependencies.
• Unbounded tpl.
• Invalid recipe schema.
• Missing fact declarations.
• Unsafe importer policy.

Variant-specific:

• Bad values.
• Missing target fact values.
• Policy scanner findings.
• RBAC/webhook/CRD footprint.
• Persistence/ingress/TLS/security context choices.
• Fresh-install versus reuse-existing-resource behavior.
• Approval, promotion, rollback, and target assignment state.

Result Object

Use both:

• ScanResult per renderedManifestSet@sha.
• VariantRevisionResult per immutable variant revision.
• InitiativeResult as an aggregate roll-up across variants/revisions.

The per-manifest-set result is the scan audit primitive. The variant revision is the user-facing approval and promotion primitive. The initiative result is the workflow/dashboard primitive.

8. What We May Still Be Missing

After reviewing the conversation and the legacy 500-chart feature matrix, the likely missing or under-specified areas are:

1. Chart tests as first-class checks: Helm test hooks should probably become optional post-render or post-install test actions, not just "hooks".
2. Notes and human instructions: NOTES.txt sometimes carries required operational steps. We need a policy for extracting or preserving operator notes.
3. Image resolution: scanners inspect image strings, but mutable image tags can still move. We need optional image digest resolution as a render or scan step.
4. Policy database drift: scanner output can change when vulnerability DBs update. Receipts must include scanner database/policy bundle versions.
5. CRD schema-dependent validation: kubeconform-style checks need the right CRD schemas for custom resources, not just built-in Kubernetes schemas.
6. Admission-controller reality: rendered YAML can pass static scans but fail target admission policies. A dry-run/server-side validation stage may be needed for real targets.
7. Secret value scanning: rendered Secrets may be withheld from uploaded Units, but install gating still needs a safe way to validate secret shape without leaking material.
8. Cross-resource references: Services, ServiceAccounts, Secrets, PVCs, Ingress classes, and RBAC references need graph checks, not only object-local checks.
9. Subchart value propagation: umbrella charts can pass values deeply into dependencies. Variant definitions must include subchart values explicitly.
10. Library charts: they do not render resources but strongly affect templates. They must be represented in the source lock and importer diagnostics.
11. Post-renderers: Helm supports post-renderers. If supported, they need to become explicit recipe/Kustomize/function stages; otherwise reject.
12. Upgrade/downgrade semantics: .Release.IsUpgrade, hook delete policies, CRD upgrades, and PVC retention need explicit phase variants.
13. Namespace and cluster-scope collisions: cluster-scoped resources need ownership and conflict checks across installs, not just within one rendered set.
14. Remote values or generated values files: if a workflow fetches values from URLs or CI scripts, that source must be captured as an input artifact.
15. OCI registry throttling/availability: source-acquisition failure is not chart behavior, but it affects import reliability. Mirroring may be part of the product story.
16. False positives in static chart scanning: the legacy top-500 matrix is a source scan heuristic. It is good enough to prioritize controls, not enough to certify a chart. New matrices must be generated from chart proof artifacts and receipts.
17. Bounded capability profiles: we should name the supported Kubernetes/API profiles rather than imply an unbounded continuum.
18. Scanner coverage gaps: Snyk/Trivy/Checkov/Kubescape overlap but do not fully substitute for ConfigHub recipe/fact/variant checks.
19. Operator override governance: raw manifest slots and tpl need role/policy controls, not just technical receipts.
20. Receipt UX: the receipt has to be understandable to Helm users. A receipt no one can read will not build trust.
21. Values dead-key detection: the attached note calls out values that do not apply without warning. Helm does not reliably prove that a values path affected output. The importer should report unknown values, unused values where detectable, and field-level provenance for generated manifests where possible.
22. Field ownership across tools: Helm, GitOps controllers, operators, and ConfigHub functions can all touch the same fields. The operate model needs ownership/conflict checks, not just render determinism.
23. Intended versus applied versus observed live: scanning rendered YAML is necessary but not enough. ConfigHub Server should store intended state and applied-operation receipts, while cub-scout, GitOps, CI/CD, or other external observers submit live observation receipts with freshness.
24. Variant propagation semantics: "deploy to prod" must mean promote an approved variant revision while preserving prod-only constraints, not copy dev YAML blindly.
25. Rollback semantics: rollback must be scoped to a variant/target and operation, not a Git revert that pulls unrelated changes with it.

9. Recommended Product Defaults

Start with these defaults:

• Import requires pinned chart bytes and dependency lock/digests.
• Import fails on hidden live cluster access.
• lookup must become a recipe-declared target fact requirement.
• Random/time/cert/password generation must become generated facts or secrets.
• tpl is allowed only for declared values paths and is visible in diagnostics.
• Raw manifest injection is disabled by default for trusted base variants, allowed only in explicit extension variants.
• Hooks are split into test hooks, install-phase hooks, upgrade/delete lifecycle actions, explicit skips, and unsupported procedural hooks. Hook templates can be inventoried deterministically; hook execution is proven only by target-aware lifecycle receipts and live observations.
• Capability profiles are named and finite for scanning.
• Every standard variant is rendered and scanned in bulk.
• Install is gated on the exact selected variant revision and its rendered manifest set.
• Receipts include source, dependency lock, recipe, variant, facts, renderer, overlays/functions, manifest digest, scanner versions, and scan results.

That is the cleanest version of The Plan.

10. What helm-expt Must Prove

The repo rewrite should make these artifacts visible:

• Corpus manifest: chart name, version, source, category.
• Core recipe candidates.
• Bounded install variants.
• Rendered release object snapshots.
• Per-variant diffs.
• Policy and misconfiguration scan results.
• Verified install gate receipts.
• Upgrade simulation: old chart plus customizations to new chart conflicts.
• Promotion example: staging rendered revision promoted to prod without re-rendering.
• Failure catalog: unsupported hooks, missing schemas, conflicting overrides, CRD risks.
• One 60-second skeptical-engineer walkthrough.

The repo should not merely say "top 500 charts". It should show:

Helm complexity
  -> explicit ConfigHub control point
  -> deterministic variant revision
  -> scanned and gated rendered objects