Explore CUE embedding semantics experiment

[myitcv]

Is your feature request related to a problem? Please describe.

helm2cue relies heavily on struct embedding for helper includes. When a helper produces structured YAML (labels, annotations, etc.), the generated CUE embeds the helper reference into the parent struct:

metadata: {
    name: "test"
    labels: {
        _myapp_labels
        extra: "field"
    }
}

The current CUE embedding semantics implicitly open closed structs, which can have surprising interactions with schema validation. The generated CUE works correctly today, but the implicit opening behavior means the relationship between embedding and struct closedness is not always obvious from reading the output.

Describe the solution you'd like

CUE's proposed experiment to eliminate embedding-based struct opening (cue-lang/cue#4032) introduces an explicit postfix ... operator for recursively opening composite structs. Instead of implicit opening through embedding, code would use {x...} to explicitly open a struct.

Explore this experiment to:

1. Determine whether helm2cue's embedding patterns need the implicit opening behavior, or whether explicit ... would be more correct.
2. Evaluate what changes to the generated CUE would be needed under the new semantics.
3. Check whether any current output relies on implicit opening and would break.
4. Provide feedback on the proposal from the perspective of a code generator.

Additional context

Upstream discussion: cue-lang/cue#4032

[myitcv]

Analysis: Embedding Semantics Experiment Impact on helm2cue

This analysis is based on the embedding semantics proposal (discussion #4032) and a review of all generated CUE patterns in helm2cue.

Background

The embedding semantics experiment proposes changes to how CUE handles closedness with respect to embeddings. The key change: embedding a value no longer implicitly "opens" the enclosing struct. Instead, to allow additional fields, you must explicitly use ... (the top-level open marker). The proposal introduces the @experiment(embed) attribute to opt in.

Currently in CUE, embedding a definition opens the struct to allow fields beyond those in the definition. The experiment makes this explicit — if you embed a closed definition but want extra fields, you add ....

Pattern 1: #values schema with ... (open structs)

helm2cue generates open struct schemas with explicit ...:

#values: {
    env?:          bool | number | string | null
    replicaCount?: bool | number | string | null
    serviceAccount!: {
        name!: bool | number | string | null
        ...
    }
    image?: {
        repository!: bool | number | string | null
        tag!:        bool | number | string | null
        ...
    }
    ...
}

Impact: helm2cue already emits ... on every struct in the #values schema (because Helm charts allow arbitrary additional values). Under the new embedding semantics, explicit ... is the required way to express openness. helm2cue is already doing the right thing — no change needed.

Verdict: Already compatible.

Pattern 2: Struct helper definitions (closed by default)

Helper structs like _nonzero and _trunc do not use ...:

_nonzero: {
    #arg?: _
    out: [if #arg != _|_ { ... }, false][0]
}

_trunc: {
    #in: string
    #n:  int
    _r:  len(strings.Runes(#in))
    out: string
    if _r <= #n {out: #in}
    if _r > #n {out: strings.SliceRunes(#in, 0, #n)}
}

Impact: These are standalone computation structs. They don't embed anything, and they don't need to be open. Under the new semantics, they remain closed (no embeddings to change the behaviour). No impact.

Verdict: No impact.

Pattern 3: Struct helper embedding at call sites

Struct helpers are referenced at call sites:

metadata: {
    name:   _simple_app_fullname
    labels: _simple_app_labels
}

Here _simple_app_labels is a value reference (not an embedding). The labels struct is:

_simple_app_labels: {
    "helm.sh/chart":                _simple_app_chart
    "app.kubernetes.io/name":       _simple_app_name
    "app.kubernetes.io/instance":   #release.Name
    "app.kubernetes.io/version":    "\(#chart.AppVersion)"
    "app.kubernetes.io/managed-by": "Helm"
}

And labels: _simple_app_labels is a field assignment, not an embedding. The embedding semantics change affects X when written as an embedding (bare X at struct level), not when used as a field value (labels: X).

Impact: The simple-app example doesn't use struct embeddings in the generated templates. However, some Helm charts use patterns where a helper produces fields that should merge into the enclosing struct:

metadata:
  labels:
    {{- include "myapp.labels" . | nindent 4 }}

When this appears at the struct level (not as a field value), helm2cue currently generates the helper reference as an embedding. Under the new experiment:

• If the helper is a definition (starts with #), embedding it would no longer open the enclosing struct. But helm2cue uses hidden fields (_myapp_labels), not definitions — hidden fields are not closed, so embedding them is unaffected.
• If the embedding target were a definition, we'd need explicit ... in the enclosing struct. But this doesn't arise in practice.

Verdict: No impact (helm2cue embeds hidden fields, not definitions).

Pattern 4: Helper invocation via unification

The (_helper & {#arg: expr}).out pattern:

replicas: [if (_nonzero & {
    #arg: #values.replicaCount
}).out {
    #values.replicaCount
}, 1][0]

Here _nonzero is unified with {#arg: ...}. The _nonzero struct contains #arg?: _ and out:. The unified struct has exactly these fields plus the provided #arg value.

Impact under new semantics: The {#arg: #values.replicaCount} literal is open (struct literals are open by default). Unifying it with _nonzero (also open, since it's a hidden field not a definition) works as before. If _nonzero were a definition (#nonzero), the struct literal would need to match its shape — but since the literal only provides #arg which #nonzero declares, this would still work.

Verdict: No impact.

Pattern 5: Parameterised helper call with embedding (_helper & {#arg: ..., _})

The serviceAccountName pattern uses _ (top value) as an embedding to open the result:

serviceAccountName: _simple_app_serviceAccountName & {
    #arg: #values.serviceAccount
    _
}

The bare _ here is an embedding of top, used to ensure the result is open.

Impact under new semantics: Under the experiment, the embedding of _ would no longer implicitly open the struct. However, _ (top) is neither closed nor a definition — it's the unconstrained value. The proposal primarily affects embeddings of closed values (definitions). Embedding _ should remain a no-op/open-marker. But this is worth verifying.

If the behaviour of _ as an embedding changes, helm2cue would need to emit ... instead of _ to express openness. This is a minor code change (emit ... instead of _).

Verdict: Minor risk — verify that _ embedding behaviour is preserved. If not, replace _ with ... in the generated output.

Pattern 6: Output list structure

Template output is wrapped in lists:

deployment: [
    {
        apiVersion: "apps/v1"
        kind:       "Deployment"
        ...
    },
]

Impact: List elements are struct literals, not embeddings. No impact.

Verdict: No impact.

Pattern 7: results aggregation (results.cue)

The generated results.cue typically aggregates all template outputs:

results: deployment + configmap + service + ...

This is value concatenation, not embedding. No impact.

Verdict: No impact.

Summary

Pattern	Frequency	Impact	Action needed
#values with ...	1 per chart	Already compatible	None
Helper struct definitions	Per helper	No impact	None
Struct helper at call site (field value)	High	No impact	None
Struct helper embedding (bare reference)	Medium	No impact (hidden fields, not defs)	None
(_helper & {#arg}).out unification	Very high	No impact	None
_helper & {#arg, _} with _ embedding	Low	Minor risk	Verify _ behaviour; may need ...
Output list wrappers	Per template	No impact	None
results aggregation	1 per chart	No impact	None

Conclusion

The embedding semantics experiment has very low impact on helm2cue's generated CUE. The main reasons:

1. helm2cue already uses explicit ... in #values schemas, which is exactly what the experiment encourages.
2. Helpers use hidden fields (_name), not definitions (#name), so embedding them doesn't trigger closedness changes.
3. Most helper usage is via field assignment or unification, not via bare embedding at struct level.

The one area to watch is Pattern 5: the use of bare _ as an embedding to express openness in parameterised helper call sites. If the experiment changes how _ behaves as an embedding, helm2cue would need a trivial fix (emit ... instead of _). This is a one-line code change.

No proactive code changes are recommended. When the experiment stabilises, verify Pattern 5 and adjust if necessary.