override

type Document struct {
	APIVersion string  `yaml:"apiVersion"`
	Overrides  []Entry `yaml:"overrides"`
}

type Entry struct {
	// Component names the component that generates the workload: net, machina,
	// gantry or metalman.
	Component string `yaml:"component"`

	// Kind is Deployment or DaemonSet. Together with Component it identifies
	// every workload the operator emits today, so users never have to
	// reconstruct a derived per-Site name.
	Kind string `yaml:"kind"`

	// Sites selects which Sites to affect, for per-Site components only.
	//
	// A nil slice means every Site. An explicitly empty slice is a validation
	// error, because it is far more likely to be a mistake than an intent to
	// match nothing. Naming a Site that does not exist is inert and reported,
	// not fatal: a document may legitimately be written before its Site.
	Sites []string `yaml:"sites,omitempty"`

	// AddContainers and AddInitContainers name containers this entry intends to
	// create rather than modify.
	//
	// Strategic merge cannot tell a sidecar from a typo: both are "this name is
	// not present", and merging by name silently creates a container either
	// way. Entries are therefore modify-only unless a name is listed here, so a
	// patch meaning to raise a limit on machina-controller but spelling it
	// machina-contoller fails instead of adding an image-less container.
	AddContainers     []string `yaml:"addContainers,omitempty"`
	AddInitContainers []string `yaml:"addInitContainers,omitempty"`

	// ExtraArgs appends arguments to a container, keyed by container name.
	//
	// It exists because args and command carry no patchMergeKey, so strategic
	// merge replaces them wholesale: a patch adding one flag drops every
	// operator-injected flag and will not receive new ones on upgrade. metalman
	// makes that concrete, since its args begin with the serve-pxe subcommand.
	ExtraArgs map[string][]string `yaml:"extraArgs,omitempty"`

	// Patch is a strategic merge patch applied to the whole workload object, so
	// metadata, spec.replicas and the pod template are all reachable through
	// one field.
	Patch map[string]any `yaml:"patch,omitempty"`
}

type Problem struct {
	// Key is the ConfigMap key the problem was found in.
	Key string

	// Source is set for an entry-level problem and nil for a key-level one.
	Source *Source

	// Component, Kind and Sites describe what the offending entry could have
	// targeted, and are only meaningful for an entry-level problem.
	//
	// An empty Component means the entry could never resolve to a workload at
	// all, because resolution matches on component. An empty Kind means every
	// kind the component emits. Nil Sites means every Site.
	Component string
	Kind      string
	Sites     []string

	Err error
}

type Report struct {
	// Workloads describes each workload an override resolved to, whether or not
	// it succeeded.
	Workloads []WorkloadResult

	// UnmatchedSites names Sites an entry selected that do not exist. Inert and
	// reported, never fatal.
	UnmatchedSites []string

	// InertEntries are entries that matched no workload in this pass.
	InertEntries []Source

	// Withheld names the operations removed from the plan because their
	// overrides could not be used, attributed to the component and Site that
	// planned them.
	//
	// The running workload is deliberately left as it is, but the component
	// did not write what it planned, so it must not report itself reconciled.
	// Without this the object was simply absent from the plan and nothing
	// downstream could tell that from "never planned".
	Withheld []WithheldOperation
}

type Resolution struct {
	// Targets are the workloads at least one entry resolves to.
	Targets []Target

	// UnmatchedSites names Sites an entry selected that do not exist.
	//
	// These are reported rather than fatal. A document may legitimately be
	// written before its Site exists, and deleting a Site must not retroactively
	// invalidate an unrelated override.
	UnmatchedSites []string

	// InertEntries are entries that resolved to no workload at all, so a user
	// can tell "applied nothing" from "matched nothing".
	InertEntries []Source
}

type Source struct {
	// Key is the ConfigMap data key the document was read from.
	Key string

	// Index is the entry's position in that document's overrides list.
	Index int
}

type SourcedEntry struct {
	Entry  Entry
	Source Source
}

type Target struct {
	// Index is the position of the operation within the plan.
	Index int

	// Ref identifies the workload, for messages and status.
	Ref component.ObjectRef

	// Site is the Site the workload belongs to, empty for cluster singletons.
	// Status is published per Site, so results have to carry it.
	Site string

	// Contributors are the entries resolving to this workload, ordered by
	// sorted ConfigMap key then position within that key's document.
	Contributors []SourcedEntry
}

type WithheldOperation struct {
	Ref       component.ObjectRef
	Component string
	Site      string
	Err       error
}

type WorkloadResult struct {
	Ref component.ObjectRef

	// Site is the Site the workload belongs to, empty for cluster singletons.
	Site string

	// Hash is the contributor hash merged into the object.
	Hash string

	// Sources names the contributing entries.
	Sources []Source

	// VersionDrift is set when the override changed a container image.
	VersionDrift string

	// Err is set when this workload could not be overridden. The operation is
	// dropped from the plan rather than applied un-overridden, so the running
	// workload is left as it is.
	Err error
}