kernel

package
v1.0.0-alpha.27 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 8, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package kernel exposes the OPM runtime as a single struct, Kernel.

Kernel owns its *cue.Context and its *schema.Cache for its entire lifetime. Construction is New plus two options, WithSchemaLoader and WithRegistry; the kernel exposes no injection slot that no kernel operation reads. Downstream binaries (CLI, controller, Crossplane function) construct one Kernel per goroutine and call methods on it instead of importing the individual loader / module / validate packages.

Surface

One tier: every artifact a frontend can hold comes from an acquire verb, or from the package constructor it already has a value for.

There is no second, value-only tier: a caller that wants the raw value of an acquired artifact reads its Package field, and a caller holding a value it built itself calls module.NewModuleFromValue or platform.NewPlatformFromValue directly. The registry mapping is WithRegistry for every one of these operations, the schema cache included; no verb takes a per-call override.

Goroutine safety

A single Kernel is NOT safe for concurrent use across its own method calls. The owned *cue.Context (acquisition, synthesis and validation build in it) is driven single-threaded; sharing one Kernel between goroutines can cause data races inside CUE evaluation. Callers that need concurrency MUST construct one Kernel per goroutine.

Kernel.Render shares nothing between renders (ADR-005, enhancement 0019 D8). Each render is its own CUE build in a fresh cue.Context created for that call and dropped when Render returns; the Kernel's own context is not used, no built value is retained between calls, and a caller cannot obtain one to hold. Concurrency is across renders, never within one: a consumer rendering from several goroutines gives each goroutine its own Kernel and calls Render, with no shared platform value and no mutex. There is no materialized platform to share and no serialised render path; the earlier shared-platform contract (ADR-002) is superseded, not supported.

A render is single-threaded and its working set grows with the module, so a render pool is sized by memory rather than by core count: about 61 MB plus 7.75 MB per component per concurrent render (0019 experiment 08), and throughput saturates at roughly physical cores divided by 1.6 renders in flight. Size against the largest module the pool will see.

One-Kernel-per-goroutine example 

func renderAll(ctx context.Context, platformDir string, instanceDirs []string) error {
    var wg sync.WaitGroup
    errs := make(chan error, len(instanceDirs))
    for _, dir := range instanceDirs {
        wg.Add(1)
        go func(dir string) {
            defer wg.Done()
            k := kernel.New() // one Kernel per goroutine
            plat, err := k.AcquirePlatformFromDir(ctx, platformDir)
            if err != nil {
                errs <- err
                return
            }
            inst, err := k.AcquireInstanceFromDir(ctx, dir)
            if err != nil {
                errs <- err
                return
            }
            if _, err := k.Render(ctx, kernel.RenderInput{Instance: inst, Platform: plat, RuntimeName: "opm-cli"}); err != nil {
                errs <- err
            }
        }(dir)
    }
    wg.Wait()
    close(errs)
    for err := range errs {
        if err != nil {
            return err
        }
    }
    return nil
}

Rendering

Kernel.Render is the kernel's single render verb. It takes a source-carrying instance (Kernel.AcquireInstanceFromDir or Kernel.SynthesizeInstance) and a source-carrying platform (Kernel.AcquirePlatformFromDir: a platform is a CUE module on disk that imports its catalogs), stages one generated render module that imports both, builds it once, and decodes the matching verdicts (RenderDiagnostics) and the rendered output (RenderResult.Compiled, one entry per rendered object as a *Compiled carrying instance, component and transformer provenance). Matching and transformer execution are CUE inside the build, not Go; the build reports its verdicts as data and the kernel's fail-closed gate turns an unresolved demand, an unmatched component or an over-subscribed provider-fulfilled contract into a *RenderError that carries the full diagnostics, with the typed causes reachable through errors.As. Catalog version skew (the instance module requiring a newer OPM-namespace build than the platform carries) marks a resolved-versions row Newer by default (SkewWarn) or refuses before evaluation (SkewRefuse).

A render result carries no presentation strings. The two advisory facts a render can report are rows on the diagnostics: an unhandled optional trait on RenderDiagnostics.UnhandledTraits, and a module requiring a newer build than the platform carries on a RenderDiagnostics.ResolvedVersions row with Newer set. A frontend words both: 

for comp, traits := range result.Diagnostics.UnhandledTraits {
	for _, fqn := range traits {
		log.Printf("component %q: trait %q is unhandled", comp, fqn)
	}
}
for _, r := range result.Diagnostics.ResolvedVersions {
	if r.Newer {
		log.Printf("%s: module requires %s, platform carries %s", r.Path, r.ModuleVersion, r.PlatformVersion)
	}
}

A dry run is Render with the output discarded: the build evaluates every matched pair regardless, and RenderDiagnostics carries the pairing diagnosis (Pairs, Unmatched, Unresolved, Unify, UnhandledTraits, OverSubscribed, ResolvedVersions). There is no separate match verb.

Render consumes the instance as processed: values are validated where they are applied. Kernel.AcquireInstanceFromDir unifies its trailing Source values inside the package build and checks them against the module's `#config` at their own positions; Kernel.SynthesizeInstance does the same for InstanceInput.Values, rendering them into the synthesized package; both then assert concreteness on the whole built spec. Render performs no validation pass of its own.

Configuration validation

One primitive forms the validation surface: Kernel.ValidateConfigDetailed accepts an ordered slice of Source, unifies in stack order, then validates the merged value against a schema with concreteness enforced. A single value is a one-element slice. Per-source attribution flows through token.Pos.Filename populated from cue.Filename(Origin) at compile time; use Kernel.LoadSourceFromFile or Kernel.LoadSourceFromBytes to construct sources whose Value satisfies the filename contract automatically. There is no partial-mode entry: partial validation is an internal attribution pass under AcquireInstanceFromDir with extra values, not a public contract.

The primitive returns CUE-native errors. Walk them via cuelang.org/go/cue/errors.Errors / cuelang.org/go/cue/errors.Positions, or print via cuelang.org/go/cue/errors.Print. Presentation belongs to the frontend — the kernel does not ship a formatter.

A caller holding a *module.Module or *module.Instance composes its ConfigSchema() accessor with the primitive, e.g. k.ValidateConfigDetailed(m.ConfigSchema(), []kernel.Source{src}).

Advanced: CueContext accessor

Kernel.CueContext returns the underlying *cue.Context for callers that need to build [cue.Value]s outside the kernel (typically tests). Values built with this context are safe to pass back into Kernel methods. Most callers should not need this. Render never uses it: the render build has its own context.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Compiled 

type Compiled struct {
	// Value is the CUE value produced by the transformer. Concrete and
	// fully evaluated — safe to encode directly to YAML or JSON.
	Value cue.Value

	// Instance is the name of the ModuleInstance that produced this resource.
	// Was: Release
	Instance string

	// Component is the source component name within the instance.
	Component string

	// Transformer is the FQN of the transformer that produced this resource.
	Transformer string
}

Compiled is the terminal output of an OPM render: Kernel.Render emits *Compiled values carrying the rendered CUE value plus OPM provenance. It carries no platform-native fields — keeping platform vocabulary out of the kernel keeps it platform-neutral, and each consumer wraps *Compiled in its own resource type.

type InstanceInput 

type InstanceInput struct {
	// Module is the source #Module the instance deploys. Required, and it
	// MUST carry its staged source — acquire it with
	// [Kernel.AcquireModuleFromRegistry] or [Kernel.AcquireModuleFromDir].
	// Its metadata.modulePath / metadata.version identify the module the
	// synthesized package imports; because that import resolves to the
	// module's ROOT package, a module acquired from a subdirectory is
	// refused.
	Module *module.Module

	// Name is the instance name (metadata.name). Required. It must satisfy
	// the schema's #NameType regex; a violation surfaces as a CUE
	// unification error from the synthesized build.
	Name string

	// Namespace is the target namespace (metadata.namespace). Required.
	Namespace string

	// Values are the configuration sources, in stack order — the same
	// [Source] type [Kernel.ValidateConfigDetailed] and
	// [Kernel.AcquireInstanceFromDir] take. They are unified, rendered into
	// the synthesized package's values file so the merge is the schema's own
	// values unification in CUE, and checked against the module's #config at
	// their own positions after the build.
	//
	// Empty means "no values supplied": the values path is left unfilled and
	// the concreteness check then fails unless every #config field has a
	// default. Synthesis NEVER falls back to Module.debugValues; layering a
	// debug-values overlay is frontend policy.
	Values []Source

	// Labels and Annotations layer over the schema's stamped
	// module-instance.opmodel.dev/{name,uuid} labels. CUE unification merges
	// caller-supplied entries with schema-stamped ones; caller-supplied keys
	// MUST NOT collide with the schema's reserved keys.
	Labels      map[string]string
	Annotations map[string]string
}

InstanceInput is the typed input Kernel.SynthesizeInstance takes. Module, Name and Namespace are required; the rest are optional and are filled into the instance only when present, so an empty field never displaces a schema-derived one.

It carries no schema cache and no *cue.Context: the Kernel owns both, and the registry mapping is the Kernel's WithRegistry.

type Kernel 

type Kernel struct {
	// contains filtered or unexported fields
}

Kernel is the public anchor type for the OPM runtime. It owns a *cue.Context and a *schema.Cache for its lifetime.

Kernel is NOT safe for concurrent use across method calls — see the package documentation for the one-Kernel-per-goroutine pattern.

The Kernel owns exactly one *schema.Cache for its lifetime. Long- running consumers (operator, server) MUST keep the Kernel alive across operations to reuse the in-process schema cache; constructing a fresh Kernel per request pays the schema-fetch cost on every cold disk cache. The CUE module cache on disk is shared across Kernels.

func New 

func New(opts ...Option) *Kernel

New constructs a Kernel with default dependencies and applies the supplied options. Defaults are:

Seeding the loader from the registry option is what makes WithRegistry the ONE mapping every kernel operation resolves through — schema fetch included — so a consumer cannot end up rendering against an explicit mapping while its schema silently resolves from the process environment. An explicit WithSchemaLoader still wins, whatever order the options are given in: the loader is chosen after every option has been applied.

New never returns nil. The returned Kernel is NOT safe for concurrent use across method calls.

New does NOT trigger a schema load. The first Kernel method that needs the schema invokes [Cache.Get] internally, which performs the fetch lazily.

func (*Kernel) AcquireInstanceFromDir 

func (k *Kernel) AcquireInstanceFromDir(ctx context.Context, dirPath string, values ...Source) (*module.Instance, error)

AcquireInstanceFromDir loads a #ModuleInstance CUE package from a directory and returns it as a validated, source-carrying *module.Instance. The package is evaluated, run through the instance shape gate and then the kernel's instance processing — concreteness on the whole built spec, so the package must already be fully concrete, as an authored instance package is, and metadata decoding — and module.Instance.Source is stamped in on-disk mode: Overlay is nil, Root is the enclosing module root (the nearest ancestor holding cue.mod/module.cue, the directory itself when it is the root) and Pkg the package directory relative to it, so a package in a subdirectory of its module imports correctly from a follow-on build.

The trailing values sources — the same Source type Kernel.ValidateConfigDetailed takes, in stack order — layer extra values onto the package: the on-disk files under the module root are read into an in-memory overlay, the unified sources are rendered as a package file declaring `values` (opm-values.cue) beside the package's own files, and the package is built in one pass through the same instance shape gate, so the merge is the schema's own values unification in CUE. Nothing is filled from Go and nothing is written into the caller's directory. The returned Source is then overlay mode: the same Root and Pkg, with Overlay carrying every on-disk .cue file plus the rendered values file, exactly as load.Config.Overlay expects, so Kernel.Render imports the layered package by source. A source conflicting with the package's own values or the module's #config fails acquisition with the conflict attributed to the source (its Origin), exactly as layered validation reports it.

Passing no sources is the "no values supplied" path: the package is built from disk as authored and the Source stays on-disk mode.

This is the same bar Kernel.SynthesizeInstance output meets. Loader failures propagate unchanged (missing directory, no package, or a shape-gate sentinel); a non-concrete package surfaces the concreteness error, framed `instance "<name>": …`. No partial instance is returned.

func (*Kernel) AcquireModuleFromDir 

func (k *Kernel) AcquireModuleFromDir(_ context.Context, dirPath string) (*module.Module, error)

AcquireModuleFromDir loads a #Module CUE package from a directory and returns it as a typed, source-carrying *module.Module. It is the directory peer of Kernel.AcquireModuleFromRegistry: the package is evaluated and shape-gated exactly as the registry path gates a fetched module, module.NewModuleFromValue constructs the typed artifact, and module.Source is stamped in OVERLAY mode — Root the enclosing module root (the nearest ancestor holding cue.mod/module.cue, the directory itself when it is the root or when no ancestor holds one), Pkg the package directory relative to it, and Overlay every .cue file under Root (the module's own cue.mod/module.cue included) keyed by its absolute path.

Stamping the overlay is what makes the acquired module a valid Kernel.SynthesizeInstance input (module.Module.HasSource reports true): synthesis stages the instance package inside the module's own tree, so a frontend rendering from a module directory no longer walks that tree itself. Because the synthesized package imports the module by its module path — which resolves to the module's ROOT package — synthesis refuses a module whose Source.Pkg is non-empty; acquiring a subdirectory package is still valid for reading its value and metadata.

The registry mapping is the kernel's (WithRegistry), applied via the load configuration's environment and never os.Setenv. The caller's directory is never written to.

Shape-gate failures propagate unchanged (missing directory, no package, or a sentinel such as oerrors.ErrWrongKind); no partial module is returned.

func (*Kernel) AcquireModuleFromRegistry 

func (k *Kernel) AcquireModuleFromRegistry(ctx context.Context, modPath, version string) (*module.Module, error)

AcquireModuleFromRegistry loads a #Module published in an OCI registry by its major-qualified path (e.g. "example.com/modules/hello@v0") and version (e.g. "v0.0.2"), using the kernel's *cue.Context and configured registry (set via WithRegistry, inheriting CUE_REGISTRY from the process environment when unset). It returns a decoded *module.Module whose staged source (module.Source) is populated, so the module can be reused as the main module of a follow-on build — notably by Kernel.SynthesizeInstance, which stages the instance inside the module's own root so the module's already-tidied cue.mod/module.cue drives transitive dependency resolution. A caller that wants only the raw module value reads Module.Package.

func (*Kernel) AcquirePlatformFromDir 

func (k *Kernel) AcquirePlatformFromDir(_ context.Context, dirPath string) (*platform.Platform, error)

AcquirePlatformFromDir loads a #Platform CUE package from a directory and returns it as a typed, source-carrying *platform.Platform. The package is evaluated and run through the platform shape gate, then platform.NewPlatformFromValue constructs the typed artifact and platform.Platform.Source is stamped in on-disk mode: Root is the enclosing module root (the nearest ancestor holding cue.mod/module.cue, the directory itself when it is the root), Pkg the package directory relative to it, and Overlay nil.

It is the directory peer of Kernel.AcquireModuleFromRegistry ("Acquire" returns a typed artifact that knows where its source lives) and the only way to obtain a platform: a caller that wants the raw value reads Platform.Package. The registry mapping used for the platform's catalog imports is the kernel's (WithRegistry), applied via the load configuration's environment and never os.Setenv; the verb takes no per-call override.

Loader failures propagate unchanged (missing directory, no package, or a shape-gate sentinel such as oerrors.ErrWrongKind); no partial platform is returned.

func (*Kernel) CueContext 

func (k *Kernel) CueContext() *cue.Context

CueContext returns the *cue.Context owned by this Kernel.

Advanced: most callers do not need this. Use it only when building [cue.Value]s outside the kernel (typically tests or programmatic CUE construction). Values built with this context are safe to pass back into Kernel methods. The same *cue.Context is returned for the lifetime of the Kernel.

func (*Kernel) LoadSourceFromBytes 

func (k *Kernel) LoadSourceFromBytes(origin string, b []byte) (Source, error)

LoadSourceFromBytes compiles b into a Source with cue.Filename(origin) baked into the resulting cue.Value, so that any subsequent validation error positions carry origin via token.Pos.Filename. A caller holding a string passes []byte(s).

Returns an error if compilation fails (the returned Source is the zero value in that case).

func (*Kernel) LoadSourceFromFile 

func (k *Kernel) LoadSourceFromFile(path string) (Source, error)

LoadSourceFromFile reads a values file from disk, compiles it via cuelang.org/go/cue/load.Instances (which populates cue.Filename automatically with the file's absolute path), and returns a Source whose Origin matches the absolute path so per-position diagnostics remain consistent with the file the user wrote.

Auto-unwrap: if the loaded value has a top-level `values:` field that exists and reports no error, that field is returned as the Source.Value. Otherwise the whole evaluated file value is returned.

func (*Kernel) Render 

func (k *Kernel) Render(ctx context.Context, in RenderInput) (*RenderResult, error)

Render renders an instance against a platform as ONE CUE build (enhancement 0019 D9): it stages a generated render module in a per-render temporary directory (the promoted cue.mod, D13; directory replacements bringing both inputs in; the embedded matching and execution glue), verifies the promoted list covers every OPM-namespace path either input requires, applies the skew policy (D7/D18), builds the module once in a fresh cue.Context that is dropped when Render returns (D8), and decodes `diagnostics` and `rendered` off the built value.

The Kernel's own context is not used and no built value survives the call except the returned output; repeated renders share nothing. The staging directory is removed on return, success or failure. Registry resolution for the platform's catalog imports uses WithRegistry when set, else the process CUE_REGISTRY, plumbed through the load configuration only.

Refusals before evaluation (missing Source, uncovered OPM path, skew under SkewRefuse) return plain errors; refusals after evaluation return a *RenderError carrying the decoded diagnostics.

func (*Kernel) SchemaCache 

func (k *Kernel) SchemaCache() *schema.Cache

SchemaCache returns the *schema.Cache owned by this Kernel. The same pointer is returned for the lifetime of the Kernel; callers MAY hold it across operations to ensure cache reuse.

Calling SchemaCache does NOT trigger a schema load. Only the first schema.Cache.Get invocation contacts CUE; the load is lazy and memoized.

Typical use: read schema.Cache.ResolvedVersion for diagnostics after a schema-touching operation has run. Nothing needs to be passed back in — every kernel operation that needs the schema, instance synthesis included, resolves it through this cache on its own.

func (*Kernel) SynthesizeInstance 

func (k *Kernel) SynthesizeInstance(_ context.Context, in InstanceInput) (*module.Instance, error)

SynthesizeInstance builds a *module.Instance from typed in-memory inputs. It is the entry point for a caller that holds a Module and needs a fully validated instance, mirroring Kernel.AcquireInstanceFromDir for a directory-based CUE package; the module it takes comes from Kernel.AcquireModuleFromRegistry or Kernel.AcquireModuleFromDir.

The method stages a package importing the module inside the module's own staged source tree, renders the unified in.Values into it, and builds it once so CUE derives uuid, components, auto-secrets and standard labels and performs the values merge against the module's #config. It then checks the values sources against #config at their own positions — so a violation is reported with the source's Origin rather than the rendered values file — asserts concreteness on the whole built spec and decodes instance metadata. The schema is the Kernel's own cache; no additional values source is consulted.

The returned instance carries module.Instance.Source: the staged tree the build evaluated, in overlay mode, with Pkg naming the reserved instance subdirectory inside the module's staged root.

A missing required input fails before any build runs, wrapping the matching sentinel from opm/errors (oerrors.ErrMissingModule, oerrors.ErrMissingName, oerrors.ErrMissingNamespace); a module with no staged source wraps oerrors.ErrMissingSource; a module acquired from a subdirectory of its CUE module fails stating the root-package requirement.

Was: SynthesizeRelease

func (*Kernel) ValidateConfigDetailed 

func (k *Kernel) ValidateConfigDetailed(schema cue.Value, sources []Source) (cue.Value, error)

ValidateConfigDetailed is the kernel's one validation entry: it unifies an ordered slice of Source values in stack order, runs the closed-schema disallowed-field walk, and asserts concreteness on the merged value via cue.Concrete(true). A single value is a one-element slice.

Per-source attribution flows through token.Pos.Filename, populated from cue.Filename(Origin) at the time each Source.Value was compiled — see Kernel.LoadSourceFromFile and Kernel.LoadSourceFromBytes for constructors that bake the filename for you.

Returns the merged cue.Value on success and the zero value on failure. The returned error is the raw CUE error tree; walk it via cuelang.org/go/cue/errors.Errors and cuelang.org/go/cue/errors.Positions, or print it via cuelang.org/go/cue/errors.Print. Presentation is outside the kernel's contract — frontends own their own formatting. Module-name framing is the caller's responsibility — wrap with fmt.Errorf if a context prefix is required.

Empty sources, a zero schema, or a merged value that does not exist all short-circuit to (zero, nil) — the "no values supplied" path documented across the kernel's validation surface.

type Option 

type Option func(*Kernel)

Option configures a Kernel at construction time. Options compose via the functional-options pattern; new options can be added in MINOR instances without breaking existing call sites. The provided options are WithSchemaLoader and WithRegistry; the Kernel exposes no injection slot that no kernel operation reads.

func WithRegistry 

func WithRegistry(registry string) Option

WithRegistry sets the ONE OCI registry mapping (CUE_REGISTRY syntax, e.g. "opmodel.dev=ghcr.io/open-platform-model") every kernel operation uses for catalog, module and schema resolution:

No acquire verb takes a per-call registry override.

Omitting this option (or passing an empty string) inherits CUE_REGISTRY from the process environment; the kernel applies no built-in default registry — the same stance as the schema loader. The mapping is never written back to the process environment; it is plumbed into the load configuration for the operation only.

func WithSchemaLoader 

func WithSchemaLoader(l schema.Loader) Option

WithSchemaLoader configures the schema.Loader used to populate the kernel's *schema.Cache. Omitting this option defaults to a schema.OCILoader carrying the kernel's WithRegistry mapping, which resolves schema.DefaultSchemaModule through it (and through CUE_REGISTRY / CUE_CACHE_DIR from the process environment when no mapping was given). The option wins over that default regardless of the order the options are passed in.

The Kernel wraps the supplied Loader in a fresh Cache; callers cannot inject a pre-built Cache. This guarantees one Kernel = one Cache, so no two Kernels accidentally share memoization. Multi-Kernel cache sharing is intentionally not exposed and may be added later as a non-breaking addition.

A nil Loader is ignored (the default OCILoader applies).

type RenderDiagnostics 

type RenderDiagnostics struct {
	// Pairs is the matched pair set in build order.
	Pairs []RenderPair

	// Unmatched lists components no transformer matched, each carrying
	// every candidate the demand walk reached for it.
	Unmatched []oerrors.UnmatchedComponent

	// Unresolved is every demand the platform failed to resolve (0010 D28):
	// an empty bucket (Disqualified empty, Alternatives naming same-base
	// keys the platform does implement) or every candidate disqualified.
	Unresolved []oerrors.UnresolvedDemand

	// Unify is every candidate the always-unify rung disqualified, one row
	// per (component, transformer) carrying the FQNs it conflicted at. The
	// verbatim CUE cause is not recoverable from inside the build (D10).
	Unify []oerrors.UnifyRefusal

	// UnhandledTraits maps a component to the effectively-optional traits
	// no matched transformer handles. Advisory: a frontend formats it.
	UnhandledTraits map[string][]string

	// FailedPairs names matched pairs whose transformer output errored.
	FailedPairs []RenderPair

	// OverSubscribed is every provider-fulfilled contract key that
	// transformers from more than one enabled registry entry require (the
	// single-provider guard, 0010 D32/D37), key-sorted. Any row refuses the
	// render through the gate.
	OverSubscribed []oerrors.OverSubscribedContract

	// ResolvedVersions holds the per-path version rows, in path order.
	ResolvedVersions []ResolvedVersion
}

RenderDiagnostics is everything the build reports as data (0019 D10), decoded into the kernel's structured types. It is populated on success and carried by *RenderError on a refusal, so a caller can always read the full verdict set. Every field is a row the build emitted, in the build's order; the kernel derives, joins and re-sorts nothing.

It also holds the two advisory facts a render can report, as rows rather than as messages: an unhandled optional trait is on UnhandledTraits, and a module requiring a newer build than the platform carries is a ResolvedVersions row with Newer set. A frontend words both.

type RenderError 

type RenderError struct {
	Diagnostics RenderDiagnostics
	Err         error
}

RenderError is a refusal after the build: the fail-closed gate (an unresolved demand, an unmatched component or an over-subscribed provider-fulfilled contract), a failed pair, or a non-concrete pair output. Diagnostics carries everything the build reported; Err carries the typed causes (*oerrors.UnresolvedDemandsError, *oerrors.UnmatchedComponentsError, *oerrors.OverSubscribedContractsError, *oerrors.TransformError), reachable through errors.As.

func (*RenderError) Error 

func (e *RenderError) Error() string

func (*RenderError) Unwrap 

func (e *RenderError) Unwrap() error

type RenderInput 

type RenderInput struct {
	// Instance is the validated instance to render. It MUST carry a Source
	// (Kernel.SynthesizeInstance, Kernel.AcquireInstanceFromDir): the render
	// build imports the instance as a package, so an evaluated value alone
	// is never sufficient.
	Instance *module.Instance

	// Platform is the platform to render against, in the D5 shape (registry
	// entries carrying their catalog by import). It MUST carry a Source
	// (Kernel.AcquirePlatformFromDir).
	Platform *platform.Platform

	// RuntimeName identifies the executing runtime; it enters the build as
	// #context.#runtimeName and is stamped on every rendered object.
	RuntimeName string

	// Skew is the response to catalog version skew. Zero is [SkewWarn].
	Skew SkewPolicy
}

RenderInput is the input of Kernel.Render.

type RenderPair 

type RenderPair struct {
	Component   string
	Transformer string
}

RenderPair names one matched (component, transformer) pair.

type RenderResult 

type RenderResult struct {
	// Compiled is the rendered output, one entry per rendered object, in
	// the build's deterministic pair order, each carrying instance,
	// component and transformer provenance.
	Compiled []*Compiled

	// Diagnostics are the matching verdicts and version rows decoded from
	// the build.
	Diagnostics RenderDiagnostics
}

RenderResult is the output of a successful Kernel.Render.

type ResolvedVersion 

type ResolvedVersion struct {
	// Path is the major-qualified module path.
	Path string

	// ModuleVersion is the build the instance module's cue.mod requires.
	ModuleVersion string

	// PlatformVersion is the build the platform module's cue.mod carries;
	// empty when the platform does not list the path (the instance's own
	// entry then resolves).
	PlatformVersion string

	// Newer is true when the instance requires a newer build than the
	// platform carries.
	Newer bool
}

ResolvedVersion is one resolved-versions row (0019 D18): for an OPM-namespace path the instance module requires, what it asked for and what the platform carries. Plain data with no severity; Newer marks the skew case the policy decided.

type SkewPolicy 

type SkewPolicy int

SkewPolicy is the caller's response to catalog version skew (enhancement 0019 D7/D18): the instance module's cue.mod requiring a NEWER build of an OPM-namespace path than the platform module carries. Exactly two responses exist; the zero value is the default. 

const (
	// SkewWarn renders against the platform's build and marks that path's
	// row on [RenderDiagnostics.ResolvedVersions] as Newer. The default;
	// the wording of any advisory is the frontend's.
	SkewWarn SkewPolicy = iota

	// SkewRefuse fails the render before evaluation with an
	// [*oerrors.SkewError] per skewed path.
	SkewRefuse
)

type Source 

type Source struct {
	// Value is the raw values payload for this source.
	//
	// Value MUST have been compiled with [cue.Filename](Origin) for
	// per-source attribution to flow into errors. Use
	// [Kernel.LoadSourceFromFile] or [Kernel.LoadSourceFromBytes] to
	// construct a Source whose Value satisfies this contract automatically.
	// Hand-built Sources MUST set the filename themselves when compiling.
	Value cue.Value

	// Origin is the stable identifier for machine-readable correlation
	// (file path, K8s object reference, composition input key). It MUST
	// match the [cue.Filename] used when Value was compiled, so error
	// positions report Origin via [token.Pos.Filename].
	Origin string
}

Source is one values input for Kernel.ValidateConfigDetailed and for the trailing values sources of Kernel.AcquireInstanceFromDir.

A Source pairs a values payload with its stable origin so that per-position diagnostics flowing out of CUE error trees carry the originating source's filename. The library does not invent a Go-typed wrapper around CUE's error attribution — instead, it relies on token.Pos.Filename, populated from cue.Filename at compile time. It carries no display label: presentation is outside the kernel's contract, and Origin is what CUE positions report.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.