fetch

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

type Kit struct {
	// Reference is the reference the caller named.
	Reference string

	// Digest is the digest the reference resolved to. A multi-platform
	// kit pins the index; a single-platform kit pins its manifest.
	Digest string

	// Image is the runtime-resolvable reference for this Kit's content.
	// When empty, Units derives a digest-pinned image from Reference and Digest.
	Image string

	// Descriptor is the published descriptor.
	Descriptor *spec.Descriptor

	// Raw is the annotation bytes Descriptor was decoded from, which
	// ValidatePublished needs alongside the struct.
	Raw []byte
}

type KitLoader func(context.Context, string) (*LoadedKit, error)

type KitSelection struct {
	Reference string

	// PublishedDescriptor is the decoded published descriptor before argument
	// and environment expansion or capability selection. It retains argument
	// declarations.
	PublishedDescriptor *spec.Descriptor

	// PublishedBytes holds the exact published descriptor bytes, preserving
	// source formatting for diagnostics and persistence.
	PublishedBytes []byte

	Selection spec.Selection
}

type LayerLoader func(ctx context.Context, layer ocispec.Descriptor) (io.ReadCloser, error)

type LayerValidator func(ctx context.Context, kits []*resolve.Unit, loaded map[string]*LoadedKit, report func(Progress)) error

type LoadedKit struct {
	Digest   digest.Digest
	Manifest ocispec.Manifest
	Config   ocispec.Image

	// Image is the runtime-resolvable reference for this Kit's content, such
	// as the store-local tag a source Kit was built under. The loader must
	// keep it consistent with the returned digest and metadata. When empty,
	// Assemble derives a digest-pinned image from the request reference.
	Image string

	// Descriptor is the published annotation, including an index annotation when
	// present. If empty, Assemble reads the selected manifest's annotation.
	Descriptor []byte
	// LayerLoader opens a fresh stream of the blob as described by the manifest,
	// with its original compression. DefaultLayerValidator closes each returned stream.
	// Nil is allowed for metadata-only assembly; DefaultLayerValidator requires it.
	LayerLoader LayerLoader
}

type Option func(*config) error

type Options struct {
	Loader KitLoader
	// CapabilitySelector receives the operation context, expanded owning Kit
	// descriptor (including DisplayName), and capability. It decides availability
	// and policy without applying effects. Descriptor and capability inputs are
	// passed by value.
	// Nil accepts KnownCapabilities; a runtime with fewer implementations supplies
	// spec.Supported with its actual claims. Groups remain atomic.
	CapabilitySelector spec.SelectCapability
	Overrides          Overrides
	// LayerValidator checks the complete set after metadata composition and
	// descriptor resolution. Nil skips layer checks without calling LayerLoader;
	// the caller is responsible for integrity, safe extraction, resource limits,
	// and cross-Kit collisions before using the image. Use DefaultLayerValidator for
	// the built-in checks or supply a validator backed by the runtime's store.
	LayerValidator LayerValidator
	// OnProgress receives serialized callbacks on the calling goroutine. It must
	// return promptly; cancellation uses Assemble's context. Nil disables events.
	OnProgress func(Progress)
}

type Overrides struct {
	// Env adds or replaces values after image defaults and Kit argument exports.
	Env map[string]string
	// WorkingDir replaces the workload working directory when non-nil.
	// A replacement must be an absolute container path.
	WorkingDir *string
}

type Progress struct {
	Stage     Stage
	State     ProgressState
	Reference string
	Layer     digest.Digest
}

type ProgressState string

type Request struct {
	// Reference is the caller's Kit identity. Client.Resolve requires an OCI
	// reference; Assemble can use source references with a custom KitLoader.
	Reference string
	Args      map[string]string
}

type ResolveOption func(*resolveOptions)

type Resolved struct {
	// Selections records decisions in dependency order, alongside the published
	// descriptors. Kits contains expanded, selected contributions.
	Selections []KitSelection

	// Descriptor is the reconciled, selected declaration set. It does not retain
	// per-Kit provenance; use Kits where a capability requires attribution.
	Descriptor *spec.Descriptor

	// Kits are selected, unmerged contributions in dependency order, providers before
	// requirers (including the workload wherever its dependencies put it).
	// Each retains its consumption reference, pinned image identity, and
	// resolved create arguments and their Env exports, including defaults.
	// Descriptor.Args is cleared because the values have already been applied.
	// This is declaration order; image layers start with the workload.
	// A Kit can contribute several selected lifecycle/context entries. Apply
	// lifecycle from Descriptor; use spec.AgentContextsOf for per-Kit bodies.
	Kits []*resolve.Unit

	// ContainerEnv contains resolved env: argument exports. Apply them as
	// environment overrides when creating the container, after the image's
	// environment defaults. They are not baked into the assembled image.
	// This is the union of Kits' Env maps. Two Kits exporting different
	// values for the same name is an error.
	ContainerEnv map[string]string

	// Warnings contains advisory findings from validating the merged
	// descriptor.
	Warnings []string
}

type Result struct {
	Image    *assemble.Image
	Resolved *Resolved
	// Environment is the full image-default + arg-export + override snapshot.
	// Values are literal; kit.env references in capability configs use this snapshot.
	Environment map[string]string
	WorkingDir  string
}

type Stage string