Documentation
¶
Overview ¶
Package platform defines the Platform and PlatformMetadata types, mirroring the #Platform definition of the OPM core schema. A Platform represents a deployment target's identity, type, and the catalogs it carries, in the unified (Metadata, Package, Source) artifact shape used elsewhere in the kernel.
A platform is a CUE module on disk that imports its catalogs: every #registry entry embeds a catalog by import and core derives the entry's version and the platform's #composedTransformers from it (enhancement 0019 D5/D17). The kernel acquires it with Kernel.AcquirePlatformFromDir, which stamps Source, and renders against it with Kernel.Render, which imports the platform package into the render build. The composed transformers are read by the render glue, in CUE, inside the build; the one derived view Go reads by path is the contract inventory (#Platform.#contracts, enhancement 0015), on demand through Platform.Contracts and never at construction.
See:
- enhancements/0019 (workspace root) — single-build render
- adr/006-single-build-artifact-construction.md (one CUE build per artifact)
- adr/005-shares-nothing-renders.md (the build's lifetime and concurrency)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ContractInventory ¶
type ContractInventory struct {
// DefinedBy maps each contract FQN an enabled catalog lists to the
// registry key (the catalog's module path) of the catalog listing it:
// the value every diagnostic prints beside the contract.
DefinedBy map[string]string `json:"definedBy"`
// RequiredBy maps each defined contract FQN to the implementation FQNs
// of every enabled transformer whose requiredResources or
// requiredTraits name it, in the build's order. Required demands only
// (0010 D32: optional consumption is tolerance, not fulfilment); a
// defined contract nothing requires maps to an empty list.
RequiredBy map[string][]string `json:"requiredBy"`
// Unfulfilled lists the provider-fulfilled resources and traits
// required by nothing on the platform. A report the operator surfaces
// as a non-gating condition (D18), never a refusal.
Unfulfilled []string `json:"unfulfilled"`
// OverSubscribed lists the provider-fulfilled resources and traits
// required by transformers from more than one catalog: what the
// generation step refuses on (0010 D37).
OverSubscribed []string `json:"overSubscribed"`
// Fulfilled is true exactly when Unfulfilled is empty.
Fulfilled bool `json:"fulfilled"`
// Routable is true exactly when OverSubscribed is empty.
Routable bool `json:"routable"`
}
ContractInventory is the decoded view of #Platform.#contracts, the inventory core derives from the enabled registry entries' contract maps and the required demands of #composedTransformers (enhancement 0015 D1, D2, D18). Every field is a report: an inventory that is not Fulfilled or not Routable is still a healthy value, and whether a generation step withholds a platform package on Routable false is that step's decision, outside this type.
`defined` (the listed members themselves) is not part of this view: its values are the catalogs' member schemas, non-concrete by construction, so there is no Go value a caller could use. A caller that wants one reads it off Platform.Package under #contracts.defined; DefinedBy carries the same key set.
type Platform ¶
type Platform struct {
// Metadata is the decoded platform-level metadata cache. Authoritative
// data lives in Package; Metadata exists for hot-path access (logging,
// name lookups). May be nil when the metadata could not be decoded.
Metadata *PlatformMetadata `json:"metadata"`
// Package is the loaded CUE value for the platform artifact, the
// evaluated form of the package Source points at.
Package cue.Value `json:"-"`
// Source is the staged source tree the platform package was loaded from,
// so a follow-on build can import the platform as a package. It is
// stamped by Kernel.AcquirePlatformFromDir (on-disk mode, the loaded
// directory) and is nil for platforms constructed from a bare value
// (NewPlatformFromValue). Source is the render input: Kernel.Render
// imports the platform package from it, so a platform without Source
// cannot be rendered against. No other kernel operation reads it.
Source *Source `json:"-"`
}
Platform represents an OPM #Platform artifact in the unified artifact shape: { Metadata, Package }.
Package is the source of truth: it is the loaded CUE value for the platform, and metadata decoding reads it. The derived CUE views (#composedTransformers, #contracts) are NOT decoded into Go fields at construction: the render build imports the platform package and the glue reads #composedTransformers in CUE, and the contract inventory is read off Package on demand through Platform.Contracts (enhancement 0015).
Metadata is an ergonomic decoded projection of the platform-level metadata stamped at construction. It is a cache, not a parallel source of truth — when Metadata and the corresponding subtree of Package disagree, Package wins.
func NewPlatformFromValue ¶
NewPlatformFromValue builds a *Platform from a raw CUE artifact value: it decodes PlatformMetadata from the value's metadata field (with the top-level type hoisted in) and stores the input cue.Value unmodified in Package. Errors return a nil *Platform — partial values are never returned. The returned Platform carries no Source.
func (*Platform) Contracts ¶
func (p *Platform) Contracts() (*ContractInventory, error)
Contracts decodes the contract inventory off Package on demand (#Platform.#contracts, schema.Contracts). Nothing decodes it at construction and no kernel verb calls it: the value is already built, and it is read only when a caller asks (the operator's readiness loop, a platform check), so a render pays nothing for it.
The six data fields are read by path, so the decoded set is exactly this type's field list; `defined` stays on Package (see ContractInventory). Reports, never refusals: an over-subscribed platform returns Routable false and a nil error. The one error is a platform carrying no #contracts (a value built against a core release before 2.0.0-alpha.9, or one that is not a #Platform at all), named by the missing field.
type PlatformMetadata ¶
type PlatformMetadata = schema.PlatformMetadata
PlatformMetadata is a re-export of schema.PlatformMetadata so callers can keep working with `platform.PlatformMetadata`.
type Source ¶
Source is a re-export of module.Source so callers can keep working with `platform.Source`, mirroring the PlatformMetadata re-export. One type describes the staged source tree of every artifact; see module.Source for the overlay and on-disk modes.
Source Files