ADR 0004 - Slapper Helm Renderer for the Provisioning Step

ServiceBundle.Renderer is required. For v1 only type: helm is implemented; plain_manifests is reserved as a future type. The helm variant requires repository, chart and version, plus optional default values and a valueMapping list. The pipeline must also contain exactly one provisioning step. Both checks run before any artifact is built, so a misconfigured bundle fails fast with a clear error rather than producing a half-rendered composition.

Rationale: making renderer mandatory keeps the bundle self-describing. Discovering the renderer type at convert time means the stdlib can ship one template per renderer type instead of trying to be renderer-agnostic.

StepEntry gains an inputTemplates map keyed by renderer type. The provisioning entry must use inputTemplates (not inputFile); every other step continues to use inputFile. The converter picks inputTemplates[bundle.renderer.type] and errors out if the stdlib does not ship a template for the requested type.

This keeps the stdlib in charge of the function-input shape (it knows which function consumes it and how) while letting the bundle pick which shape applies.

To inject maintainer data into the function input we introduce a structural placeholder: a single-key YAML map of the form {$slapperRef: <path>}. A small resolver walks the parsed YAML tree and replaces any node matching that shape with the value at <path>. The resolver does not recurse into resolved values, so a placeholder that resolves to a string containing {$slapperRef: …​}-looking text is left alone.

Why structural rather than textual: function inputs frequently contain {{ …​ }} (Helm, Go template), ${…​} (KCL string interpolation), and CEL. Adding another textual templating layer on top would force authors to manage escapes across overlapping syntaxes. A single-key map is unambiguous: it is either present and gets replaced, or it isn’t.

Paths use dotted segments. The first segment selects a registered root (currently only renderer); the rest is interpreted by that root. Unknown roots and missing required fields are hard errors; missing optional fields return an empty value of the appropriate kind.

The helm root publishes the bundle’s renderer fields under stable paths (for example renderer.spec.repository, renderer.spec.chart, renderer.spec.version, renderer.spec.values). Alongside each scalar field, a sibling .kcl view returns the same value already formatted as a KCL literal. A computed renderer.values.kcl view returns the merged values tree (see below) as a KCL expression.

The two flavours exist because placeholders land in different syntactic positions inside the function input. A placeholder that sits at a YAML position only needs the raw value; one that sits inside a KCL source string needs the value quoted and escaped the way KCL expects. Asking the template author to wrap values in the right syntax themselves would push the escaping problem back into the textual-templating space we deliberately avoided.

valueMapping is a list of {claimPath, target} pairs. claimPath is a leading-dot dotted path into the claim (for example .spec.parameters.size.replicas); target is a dotted path into the helm values tree. The merger deep-clones values, then for each mapping writes a marker into the values tree at target recording that the field is not a literal but a KCL expression referring to the observed XR field. The merged tree is then emitted as KCL by the pkg/converter/kcl emitter and exposed as renderer.values.kcl.

Rationale: maintainers think in terms of "this claim field drives this chart value", not in terms of KCL expressions. The merger lets them express that intent declaratively. Producing the result as KCL (rather than as a JSON patch or a CEL expression) matches the function the stdlib runs at composition time.

A valueMapping[].target may include or omit a leading dot; both are accepted. claimPath must start with a dot, this is the syntactic cue that it refers to the claim/XR tree and removes ambiguity with chart-value paths.

The boundaries matter: template and kcl are reusable for future renderer types, and renderer/helm is the only package that knows the bundle’s helm shape.

--no-stdlib remains a debug-only escape hatch (per ADR 0003). The in-tree dummy provisioning renderer continues to ignore the renderer stanza. When a bundle has a renderer set and --no-stdlib is passed, the converter logs a warning so the maintainer notices that their renderer config is being skipped.