helper

Overview ¶

Package helper is the opt-in convenience boundary of the OPM library.

Anything under opm/helper/ is opinionated frontend convenience: it makes embedding the kernel easier, but a frontend MAY skip it and call the kernel directly. The other two tiers are not optional. The kernel (opm/kernel, opm/module, opm/platform, opm/catalog, opm/schema, opm/errors and opm/internal/) is the contract every frontend (CLI, controller, Crossplane fn, future runtimes) MUST honour. The Kubernetes tier, opm/k8s/ (planned), is the contract every frontend that targets Kubernetes MUST honour.

The boundary is real in the import graph, not just described: no kernel package (opm/kernel, opm/module, opm/platform, opm/catalog, opm/schema, opm/errors and every package under opm/internal/) imports anything under it, no exported kernel signature names a type declared here, and no kernel operation returns an error whose sentinel is declared here. A depguard rule in .golangci.yml enforces it on every PR, and another keeps opm/k8s/ off this tier too.

Two subpackages:

• platformmodule — platform CUE module generation from catalog coordinates (0019:D5/D13): Generate renders cue.mod/module.cue and platform.cue deterministically from typed registry entries and a dependency list, Closure derives that list (the once-at-generation tidy) from published module files through a caller-configured registry, Files.WriteTo places the files in a caller-owned directory. The result is what (*Kernel).AcquirePlatformFromDir accepts. A frontend MAY write its platform module by hand instead.
• objectset — duplicate rendered object identities (0015:D15/D12): Duplicates scans a render's compiled objects for every Kubernetes apply identity two or more of them share, naming each producing component and transformer, and DuplicateIdentitiesError words the refusal a runtime raises from those rows between render and apply. The kernel never calls it, and a frontend applying to something other than Kubernetes MAY skip it. Apply identity is Kubernetes-specific, so it moves into opm/k8s/object with the first Kubernetes-tier package.

Earlier subpackages were folded into the kernel once it depended on them, which had made the opt-in tier mandatory:

• loader/file and loader/registry are opm/internal/loader, reached through the acquire verbs; their shape-gate sentinels are in opm/errors.
• synth is opm/internal/synth, reached through Kernel.SynthesizeInstance; its sentinels are in opm/errors.
• values is Kernel.ValidateConfigDetailed with the Source type.
• platform (the Compose helper) and platform synthesis are gone: a platform is a CUE module on disk, generated by platformmodule or hand-written, acquired with (*Kernel).AcquirePlatformFromDir.

In scope: opinionated convenience that wraps kernel primitives for a specific embedding pattern. Out of scope: anything the kernel must own (artifact types, artifact loading, synthesis, render pipeline, validation rules, version dispatch). A new subpackage is a deliberate design step, never a one-off addition.