types

type APITypes struct {
	// Object — Go type name for a single CR instance. Required for typed mode.
	// Used by ork generate to emit ObjectRegistry entries.
	// e.g. "Project" → func() runtime.Object { return &projv1.Project{} }
	Object string `yaml:"object" json:"object,omitempty" validate:"omitempty"`

	// List — Go type name for the CR list. Required for typed mode.
	// Used by ork generate to emit ListRegistry entries.
	// e.g. "ProjectList" → func() runtime.Object { return &projv1.ProjectList{} }
	List string `yaml:"objectList" json:"objectList,omitempty" validate:"omitempty"`

	// Alias — Go import alias for the API types package. Optional.
	// Auto-derived from the last two segments of Location if not set.
	// e.g. "projv1" → import projv1 "github.com/.../project/v1alpha1"
	Alias string `yaml:"alias" json:"alias,omitempty" validate:"omitempty"`

	// Group — Kubernetes API group. Required in all modes.
	// e.g. "platform.orkestra.io"
	Group string `yaml:"group" json:"group" validate:"required,hostname_rfc1123"`

	// Version — API version. Required in all modes.
	// e.g. "v1alpha1"
	Version string `yaml:"version" json:"version" validate:"required"`

	// Kind — resource Kind. Required in all modes.
	// e.g. "Project"
	Kind string `yaml:"kind" json:"kind" validate:"required"`

	// Plural — lowercase plural resource name. Required in all modes.
	// Used for REST client URL construction.
	// e.g. "projects"
	Plural string `yaml:"plural" json:"plural" validate:"required"`

	// APIPath — REST API path prefix. Default: /apis.
	// Override to /api only for core Kubernetes types (Pod, ConfigMap, etc.)
	// Almost always leave this empty — Orkestra defaults it to /apis.
	APIPath string `yaml:"apiPath" json:"apiPath,omitempty" validate:"omitempty"`

	// Location — fully qualified Go import path for the API types package.
	// Required for typed mode. Used by ork generate for import statements
	// and scheme registration in RegisterScheme().
	// Not needed for dynamic mode — omit entirely.
	// e.g. "github.com/orkspace/orkestra/api/types/project/v1alpha1"
	Location string `yaml:"location" json:"location,omitempty" validate:"omitempty"`
}

type AdmissionWebhookConfig struct {
	// Validation — include this CRD in the ValidatingWebhookConfiguration.
	// Default: true when validation rules are declared.
	Validation *bool `yaml:"validation,omitempty" json:"validation,omitempty"`

	// Mutation — include this CRD in the MutatingWebhookConfiguration.
	// Default: true when mutation rules are declared.
	Mutation *bool `yaml:"mutation,omitempty" json:"mutation,omitempty"`

	// Operations — which operations trigger the webhook.
	// Default: ["CREATE", "UPDATE"]
	// Valid values: CREATE, UPDATE, DELETE, CONNECT
	Operations []string `yaml:"operations,omitempty" json:"operations,omitempty"`
}

type AdmissionWebhookToggle struct {
	// Enabled controls whether ValidatingWebhookConfiguration and
	// MutatingWebhookConfiguration are registered at startup.
	// Default: ENABLE_ADMISSION_WEBHOOK env / false.
	Enabled *bool `yaml:"enabled,omitempty"`
}

type AllowedNamespaces []string

type AutoscaleAction struct {
	// Workers — number of concurrent reconcile goroutines.
	Workers *int `yaml:"workers,omitempty"`

	// QueueDepth — maximum queue depth before backpressure.
	QueueDepth *int `yaml:"queueDepth,omitempty"`

	// Resync — resync interval override. How frequently all CRs are
	// re-enqueued regardless of changes.
	Resync *Duration `yaml:"resync,omitempty"`
}

type AutoscaleBaseline struct {
	Workers    int
	QueueDepth int
	Resync     time.Duration
}

type AutoscaleConditions struct {
	// AnyOf — OR semantics. At least one condition in this list must be true.
	// Supports all Condition kinds: time, dayOfWeek, cron, and metric fields.
	AnyOf []Condition `yaml:"anyOf,omitempty"`

	// When — AND semantics. All conditions in this list must be true.
	// Supports: metric conditions (metrics.*, cross.<crd>.metrics.*).
	When []Condition `yaml:"when,omitempty"`
}

type AutoscaleSpec struct {
	// Interval is how often the autoscaler evaluates conditions.
	// Shorter intervals respond faster to load changes at the cost of
	// more frequent evaluation overhead (negligible in practice).
	// Default: 15s
	Interval Duration `yaml:"interval,omitempty"`

	// Cooldown is the minimum time conditions must be continuously false
	// before the baseline is restored. Prevents oscillation when metrics
	// fluctuate around a threshold.
	// Default: 2m
	Cooldown Duration `yaml:"cooldown,omitempty"`

	// Conditions declares the trigger conditions. Both blocks must pass
	// when both are declared (AND between blocks, OR within anyOf).
	Conditions AutoscaleConditions `yaml:"conditions"`

	// Do declares the override values applied when conditions are met.
	// Fields omitted in Do are not changed — only declared fields are overridden.
	Do AutoscaleAction `yaml:"do"`

	// A profile is:
	// 	a named preset that expands into a complete autoscale configuration
	// using computed heuristics tuned for a specific behavior pattern
	Profile string `yaml:"profile,omitempty"`
}

type AutoscaleState struct {
	// OverrideActive is true when an override is currently applied.
	OverrideActive bool

	// ConditionsFalseAt is the time when conditions last became continuously false.
	// Used to enforce the cooldown period before restoring the baseline.
	// Zero when conditions are currently true or have never been false.
	ConditionsFalseAt time.Time

	// CronWindowsOpenAt tracks when each cron-condition window opened.
	// Key is the cron expression string.
	// Without this, a cron fire that happens between two evaluation ticks would
	// be missed — the window must stay open across ticks until duration elapses.
	CronWindowsOpenAt map[string]time.Time
}

type CRDConversion struct {
	// StorageVersion — the version all objects are stored as internally.
	// All conversion paths route through this version.
	StorageVersion string `yaml:"storageVersion"`

	// Paths — one entry per (from, to) pair.
	// You need at least two paths for a two-version CRD:
	//   - old → storage  (up-conversion)
	//   - storage → old  (down-conversion)
	Paths []ConversionPath `yaml:"paths"`

	// UpdateCRD — when true, Orkestra patches the CRD's
	// spec.conversion.webhook.clientConfig.caBundle with the CA bundle
	// from the generated (or configured) TLS certificate at startup.
	// Set this to true when you let Orkestra manage TLS; set it to false
	// when you manage caBundle injection yourself (e.g. cert-manager).
	// Default: false.
	UpdateCRD bool `yaml:"updateCRD,omitempty"`
}

type CRDEntry struct {

	// Name — unique CRD identifier within the Katalog. Must be lowercase.
	// Injected from the map key during loading — never set from YAML.
	Name string `yaml:"-" json:"name" validate:"required,hostname_rfc1123"`

	// KatalogName — unique identifier for the the katalog in the runtime
	KatalogName string `yaml:"-" json:"katalogName,omitempty"`

	// Enabled — include this CRD in the runtime. false = skipped entirely.
	// WARNING: only set to false after stripping Orkestra finalizers from all
	// live CRs — disabled CRDs with live finalizers will cause stuck objects.
	Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`

	// Description — human-readable description. Shown in /katalog API responses.
	Description string `yaml:"description,omitempty" json:"description,omitempty" validate:"omitempty"`

	// Mode — see CRDMode for full documentation.
	// Auto-detected when omitted based on whether apiTypes.location is set.
	Mode CRDMode `yaml:"mode,omitempty" json:"mode,omitempty" validate:"omitempty,oneof=typed dynamic"`

	// ── API Types ─────────────────────────────────────────────────────────────
	// See APITypes for full field documentation.
	APITypes APITypes `yaml:"apiTypes" json:"apiTypes" validate:"required"`

	// ── Runtime objects ───────────────────────────────────────────────────────
	// Set by addRuntimeObjects() during Katalog validation. Never set from YAML.
	//
	// Typed mode:        DynamicModeObject and ListDynamicModeObject are factory functions
	//                    from ObjectRegistry and ListRegistry respectively.
	//                    TypedModeObject and ListTypedModeObject are set in BuildKatalogFromGo().
	//
	// Dynamic mode: DynamicModeObject and ListDynamicModeObject are factory functions
	//                    that return *unstructured.Unstructured and *unstructured.UnstructuredList.
	//                    These are always set by addRuntimeObjects() — never nil after validation.
	TypedModeObject       runtime.Object        `yaml:"-" json:"-"`
	ListTypedModeObject   runtime.Object        `yaml:"-" json:"-"`
	DynamicModeObject     func() runtime.Object `yaml:"-" json:"-"`
	ListDynamicModeObject func() runtime.Object `yaml:"-" json:"-"`

	// Scheme — AddToScheme function generated by controller-gen for this API type.
	// Required for typed mode so the REST client can decode API server responses.
	// Not needed for dynamic mode — the dynamic client bypasses scheme decoding.
	// Set in BuildKatalogFromGo() for Go mode. Handled by RegisterScheme() for YAML mode.
	Scheme func(s *runtime.Scheme) error `yaml:"-" json:"-"`

	// ── Computed GVK/GVR ─────────────────────────────────────────────────────
	// Set by setGroupVersionKind() during Katalog validation.
	// Derived from APITypes fields. Never set manually.
	GroupVersion         *schema.GroupVersion        `yaml:"-" json:"-"`
	GroupVersionKind     schema.GroupVersionKind     `yaml:"-" json:"-"`
	GroupVersionResource schema.GroupVersionResource `yaml:"-" json:"-"`

	// Namespaced — true if this CRD is namespace-scoped, false if cluster-scoped.
	// Default is true
	Namespaced *bool `yaml:"namespaced,omitempty" json:"namespaced,omitempty"`

	// Namespace — target namespace for namespace-scoped CRDs.
	// Informer watches this namespace only. Empty = all namespaces.
	Namespace string `yaml:"namespace,omitempty" json:"namespace,omitempty" validate:"omitempty"`

	// Workers — number of concurrent reconcile workers for this CRD.
	// Higher values increase throughput but also increase API server load.
	// 0 → uses Orkestra-level default (DEFAULT_WORKERS env var).
	Workers int `yaml:"workers,omitempty" json:"workers,omitempty" validate:"omitempty,gte=1,lte=50"`

	// WorkersActive — records number of active concurrent reconcile workers for this CRD.
	WorkersActive int `yaml:"workersActive,omitempty" json:"workersActive,omitempty" validate:"omitempty,gte=1,lte=50"`

	// Resync — full re-list interval for the informer cache.
	// Triggers a reconcile for every cached object at this interval.
	// 0 → uses Orkestra-level default (DEFAULT_RESYNC env var).
	Resync time.Duration `yaml:"resync,omitempty" json:"resync,omitempty" validate:"omitempty"`

	// DependsOn — names of other CRDs that must reach a condition before this one starts.
	// Orkestra resolves the dependency graph and starts CRDs in topological order.
	// Cycle detection runs at validation time — cycles fail fast with a clear error.
	// Supports three YAML formats (list, key-value, full map) — see DependsOnMap.
	DependsOn DependsOnMap `yaml:"dependsOn,omitempty" json:"dependsOn,omitempty"`

	// ── OperatorBox ────────────────────────────────────────────────────
	OperatorBox OperatorBoxConfig `yaml:"operatorBox,omitempty" json:"operatorBox,omitempty"`

	// ── Queue ────────────────────────────────────────────────────
	Queue Queue `yaml:"queue,omitempty" json:"queue,omitempty"`

	// Labels           []ResourceLabel  `yaml:"labels,omitempty" json:"labels,omitempty" validate:"omitempty"`
	// LabelSelector filters which resources this CRD entry reconciles.
	// Only resources whose labels match ALL declared key-value pairs are watched.
	// Required for built-in types (ConfigMap, Pod, etc.) — without a selector,
	// Orkestra would reconcile every instance in the cluster.
	// For custom CRDs this is optional — can narrow scope within a CRD.
	LabelSelector SelectorMap `yaml:"labelSelector,omitempty"`

	// FieldSelector filters which resources this CRD entry reconciles.
	// Only resources whose *fields* match ALL declared key-value expressions
	// are listed or watched. Field selectors operate on the server side and
	// support exact-match comparisons on well-known metadata paths
	// (e.g. "metadata.name", "metadata.namespace").
	//
	// Unlike label selectors, field selectors cannot match arbitrary user-defined
	// keys — only fields exposed by the Kubernetes API server. They are evaluated
	// before any client-side filtering, reducing load on the informer pipeline.
	//
	// Common use cases:
	//   - Restricting reconciliation to a specific namespace:
	//       {key: "metadata.namespace", value: "default"}
	//   - Targeting a single object by name:
	//       {key: "metadata.name", value: "my-config"}
	//
	// Field selectors are optional for all types. When omitted, Orkestra will
	// watch all objects permitted by LabelSelector and namespace restrictions.
	FieldSelector SelectorMap `yaml:"fieldSelector,omitempty"`

	// IsBuiltIn is set to true when this CRD entry was enriched from the
	// built-in Kubernetes resource registry. Used for ork validate output
	// and informational logging only — does not affect runtime behavior.
	IsBuiltIn bool `yaml:"-" json:"-"` // never serialized — runtime state only

	// IgnoreStatusPatch reports whether or not to patch the status of this CRD
	IgnoreStatusPatch bool `yaml:"ignoreStatusPatch,omitempty" json:"ignoreStatusPatch,omitempty"`

	// IgnoreObservedGeneration reports whether or not to ignore the observedGeneration field for this CRD.
	IgnoreObservedGeneration bool `yaml:"ignoreObservedGeneration,omitempty" json:"ignoreObservedGeneration,omitempty"`

	// IsStatusless reports whether this CRD has no meaningful readiness semantics.
	// These resources become "Ready" immediately upon creation.
	IsStatusless bool `yaml:"-" json:"IsStatusless,omitempty"`

	// BuiltInGroup is the display name of the API group for built-in resources.
	// "core" for resources in the core group (empty string group).
	// Only set when IsBuiltIn is true.
	BuiltInGroup string `yaml:"-" json:"-"` // never serialized

	// EnrichmentOutcome records the result of the API type enrichment phase.
	// During validation, built‑in Kubernetes kinds (e.g., Pod, Deployment, Secret)
	// are automatically enriched with their full API metadata — group, version,
	// plural, API path, and namespaced scope. This allows users to specify only:
	//
	//	apiTypes:
	//	  kind: Pod
	//
	// and rely on Orkestra to resolve all remaining fields based on the
	// Kubernetes discovery API. Custom resources are enriched using their declared
	// group/version/kind. This field is never serialized and is used internally to
	// report enrichment status and drive downstream runtime behavior.
	EnrichmentOutcome EnrichmentOutcome `yaml:"-" json:"-"` // never serialized

	// Endpoints defines which operator HTTP endpoints are enabled for this CRD.
	Endpoints EndpointsConfig `yaml:"endpoints,omitempty" json:"endpoints,omitempty"`

	// Restricted Namespaces
	RestrictedNamespaces RestrictedNamespaces `yaml:"restrictedNamespaces,omitempty" json:"restrictedNamespaces,omitempty"`

	// Allowed Namespaces
	AllowedNamespaces AllowedNamespaces `yaml:"allowedNamespaces,omitempty" json:"allowedNamespaces,omitempty"`

	// Conversion is useful for handling multi-version crd
	Conversion *CRDConversion `yaml:"conversion,omitempty" json:"conversion,omitempty"`

	// Validation is a list of rules
	Validation *ValidationConfig `yaml:"validation,omitempty" json:"validation,omitempty"`

	// Mutation is a list of rules
	Mutation *MutationConfig `yaml:"mutation,omitempty" json:"mutation,omitempty"`

	// Webhooks controls per-CRD admission webhook behaviour.
	// Only meaningful when ENABLE_ADMISSION_WEBHOOK=true.
	// By default, any CRD with Validation or Mutation rules is included
	// in the corresponding webhook configuration automatically.
	// Set validation: false or mutation: false to opt a specific CRD out of
	// admission-time interception while keeping its reconcile-time enforcement.
	Webhooks AdmissionWebhookConfig `yaml:"webhooks,omitempty" json:"webhooks,omitempty"`

	// Normalize Spec fields before rendering
	Normalize *NormalizeConfig `yaml:"normalize,omitempty"`

	// NotificationEnabled returns whether this CRD belongs to katalog with notification access
	NotificationEnabled *bool `yaml:"-" json:"-"`

	// RemoveFinalizers -> testing
	RemoveFinalizers bool `yaml:"removeFinalizers,omitempty" json:"removeFinalizers,omitempty"`
}

type CRDMode string

type Condition struct {
	// Field — dot-notation path to a field in the CR object or a runtime metric.
	// e.g. "spec.environment", "metrics.queueDepth", "cross.managed-database.metrics.queueDepth"
	Field string `yaml:"field" validate:"required"`

	// Operator — how to compare the field value.
	// See ConditionOperator constants below.
	Operator ConditionOperator `yaml:"operator,omitempty"`

	// Value — the value to compare against.
	// Not used for exists/notExists operators.
	// Supports template expressions: "{{ .metadata.name }}-prod"
	Value string `yaml:"value,omitempty"`

	// Equals is a shorthand for operator: equals.
	Equals string `yaml:"equals,omitempty"`

	// NotEquals is a shorthand for operator: notEquals.
	NotEquals string `yaml:"notEquals,omitempty"`

	// Contains is a shorthand for operator: contains.
	Contains string `yaml:"contains,omitempty"`

	// Prefix is a shorthand for operator: prefix.
	Prefix string `yaml:"prefix,omitempty"`

	// Suffix is a shorthand for operator: suffix.
	Suffix string `yaml:"suffix,omitempty"`

	// Numeric shorthands
	GreaterThan string `yaml:"greaterThan,omitempty"`
	LessThan    string `yaml:"lessThan,omitempty"`

	// Time — active when the current time is within the declared window.
	// After and Before are both optional; omit one for a half-open range.
	//   anyOf:
	//     - time:
	//         after: "08:00"
	//         before: "20:00"
	Time *TimeWindow `yaml:"time,omitempty"`

	// DayOfWeek — active on the specified days of the week.
	//   anyOf:
	//     - dayOfWeek:
	//         in: [Monday, Tuesday, Wednesday, Thursday, Friday]
	DayOfWeek *DayOfWeekCondition `yaml:"dayOfWeek,omitempty"`

	// Cron — a standard cron expression (5-field) that defines when the
	// window opens. Duration defines how long the window stays open.
	// Without Duration, the window closes after one evaluation interval.
	Cron string `yaml:"cron,omitempty"`

	// Duration — how long a cron-opened window remains active.
	Duration Duration `yaml:"duration,omitempty"`

	// Notify declares teams to alert when this condition is true.
	Notify *NotifyBlock `yaml:"notify,omitempty"`

	// Source is the HTTP fallback for cross-binary metric observation.
	// Only used when field is a cross.<crd>.metrics.* field and the CRD
	// is not registered in GlobalCrossMetricsRegistry (different binary).
	// The endpoint must be the remote operator's /katalog/{crd} URL.
	//
	//   when:
	//     - field: cross.managed-database.metrics.queueDepth
	//       greaterThan: "500"
	//       source:
	//         endpoint: "http://database-operator:8080/katalog/managed-database"
	Source *CrossSource `yaml:"source,omitempty"`
}

type ConditionOperator string

type ConfigMapKeyRef struct {
	Name string `yaml:"name" json:"name"`
	Key  string `yaml:"key" json:"key"`
}

type ConfigMapTemplateSource struct {
	// Version — OrkestraRegistry implementation version. Omit for latest.
	Version string `yaml:"version" json:"version,omitempty" validate:"omitempty"`

	// Name — ConfigMap name.
	// Default when omitted: "{{ .metadata.name }}-config"
	Name string `yaml:"name" json:"name,omitempty" validate:"omitempty"`

	// Namespace — target namespace.
	// Default when omitted: "{{ .metadata.namespace }}"
	Namespace string `yaml:"namespace" json:"namespace,omitempty" validate:"omitempty"`

	// ToNamespaces - a list of target namespaces
	// Default when omitted: "{{ .metadata.namespace }}"
	ToNamespaces []string `yaml:"toNamespaces" json:"toNamespaces,omitempty" validate:"omitempty"`

	// Data — static key-value configuration entries.
	// Values are plain strings — template expressions are not supported here.
	Data map[string]string `yaml:"data" json:"data,omitempty" validate:"omitempty"`

	// Labels — applied to ConfigMap metadata. Values support template expressions.
	Labels []ResourceLabel `yaml:"labels" json:"labels,omitempty" validate:"omitempty"`
	// FromConfigMap — name of an existing ConfigMap to copy data from.
	// Orkestra reads this at reconcile time — copies stay in sync with the source.
	FromConfigMap string `yaml:"fromConfigMap" json:"fromConfigMap,omitempty" validate:"omitempty"`

	// FromNamespace — namespace where FromConfigMap lives.
	// Default: same namespace as the CR.
	FromNamespace string `yaml:"fromNamespace" json:"fromNamespace,omitempty" validate:"omitempty"`

	// Reconcile: true — also apply this declaration as drift correction on every
	// reconcile. Equivalent to declaring the same entry under both onCreate and
	// onReconcile. When false (default), only runs on onCreate (idempotent create).
	Reconcile bool `yaml:"reconcile" json:"reconcile,omitempty" validate:"omitempty"`

	Conditions []Condition `yaml:"when,omitempty" json:"when,omitempty"`
	// ForEach declares dynamic expansion over a list field.
	// When set, one source declaration becomes N declarations — one per list element.
	// .item and .<as> are available in template expressions within this declaration.
	ForEach *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`

	// AnyOf holds OR conditions — at least one must pass for this resource to be created.
	// Works alongside the existing Conditions (when:) field which uses AND semantics.
	AnyOf []Condition `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`
}

type ConstructorDeclaration struct {
	// Location — fully qualified Go import path. Local or remote module.
	Location string `yaml:"location" json:"location" validate:"required"`

	// Function — exported constructor function name at Location.
	// e.g. "NewManagedNamespaceReconciler"
	Function string `yaml:"function" json:"function" validate:"required"`

	// Alias — Go import alias. Optional, auto-derived from Location if omitted.
	Alias string `yaml:"alias" json:"alias,omitempty" validate:"omitempty"`
}

type ConversionConfig struct {
	// Enabled controls whether the /convert endpoint is registered and the
	// CRD conversion webhook is active.
	// Default: ENABLE_CONVERSION env / false.
	Enabled *bool `yaml:"enabled,omitempty"`

	// ConversionWindow is the rolling window size for latency/throughput stats.
	// Default: CONVERSION_WINDOW env / 100.
	ConversionWindow int `yaml:"conversionWindow,omitempty"`
}

type ConversionPath struct {
	// From — the source version (bare, e.g. "v1alpha1")
	From string `yaml:"from" validate:"required"`

	// To — the target version (bare, e.g. "v1")
	To string `yaml:"to" validate:"required"`

	// Spec — the output spec in the target version's format.
	// Values support Go template expressions evaluated against the source object.
	// Static values are used as-is.
	Spec map[string]interface{} `yaml:"spec" validate:"required"`
}

type ConversionRules struct {
	Kind           string           `json:"kind"`
	StorageVersion string           `json:"storageVersion"`
	Paths          []ConversionPath `json:"paths"`
}

type ConversionVersionSpec struct {
	Version string                 `json:"version"`
	Spec    map[string]interface{} `json:"spec"`
}

type CronJobTemplateSource struct {
	// Version — OrkestraRegistry implementation version. Omit for latest.
	Version string `yaml:"version" json:"version,omitempty" validate:"omitempty"`

	// Name — CronJob name.
	// Default when omitted: "{{ .metadata.name }}-cronjob"
	Name string `yaml:"name" json:"name,omitempty" validate:"omitempty"`

	// Schedule — cron schedule expression. Required.
	// Static: "0 * * * *" (every hour)
	// Dynamic: "{{ .spec.schedule }}"
	Schedule string `yaml:"schedule" json:"schedule" validate:"required"`

	// Image — container image. Required.
	Image string `yaml:"image" json:"image" validate:"omitempty"`

	// Command — container entrypoint. Each element supports template expressions.
	Command []string `yaml:"command" json:"command,omitempty" validate:"omitempty"`

	// Args — container arguments. Each element supports template expressions.
	Args []string `yaml:"args" json:"args,omitempty" validate:"omitempty"`

	// Namespace — target namespace.
	// Default when omitted: "{{ .metadata.namespace }}"
	Namespace string `yaml:"namespace" json:"namespace,omitempty" validate:"omitempty"`

	// Labels — applied to CronJob metadata. Values support template expressions.
	Labels []ResourceLabel `yaml:"labels" json:"labels,omitempty" validate:"omitempty"`

	// Reconcile: true — also apply this declaration as drift correction on every
	// reconcile. Equivalent to declaring the same entry under both onCreate and
	// onReconcile. When false (default), only runs on onCreate (idempotent create).
	Reconcile bool `yaml:"reconcile" json:"reconcile,omitempty" validate:"omitempty"`

	Conditions []Condition `yaml:"when,omitempty" json:"when,omitempty"`

	Suspend                    string `yaml:"suspend,omitempty" json:"suspend,omitempty"`
	SuccessfulJobsHistoryLimit string `yaml:"successfulJobsHistoryLimit,omitempty" json:"successfulJobsHistoryLimit,omitempty"`
	FailedJobsHistoryLimit     string `yaml:"failedJobsHistoryLimit,omitempty" json:"failedJobsHistoryLimit,omitempty"`
	ConcurrencyPolicy          string `yaml:"concurrencyPolicy,omitempty" json:"concurrencyPolicy,omitempty"`
	StartingDeadlineSeconds    string `yaml:"startingDeadlineSeconds,omitempty" json:"startingDeadlineSeconds,omitempty"`

	// ForEach declares dynamic expansion over a list field.
	// When set, one source declaration becomes N declarations — one per list element.
	// .item and .<as> are available in template expressions within this declaration.
	ForEach *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`

	// AnyOf holds OR conditions — at least one must pass for this resource to be created.
	// Works alongside the existing Conditions (when:) field which uses AND semantics.
	AnyOf []Condition `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`

	// WorkingDirectory sets the container's working directory (container.WorkingDir).
	// Useful for Git-backed pipelines where build/test commands must run inside
	// a checked-out repository path.
	WorkingDirectory string `yaml:"workingDirectory,omitempty" json:"workingDirectory,omitempty"`
}

type CrossCRDDeclaration struct {
	// Crd is the target CRD name (lowercase, matches the map key in spec.crds).
	//   crd: database
	Crd string `yaml:"crd"`

	// LabelSelector is a label key/value pair for label-based informer lookup.
	// Mutually exclusive with Kind.
	LabelSelector map[string]string `yaml:"labelSelector,omitempty"`

	// Selector identifies which CR instance to observe.
	Selector CrossSelector `yaml:"selector"`

	// As is the key under .cross.* where the result is accessible.
	//   as: database → .cross.database.status.phase
	// Default: same as Crd.
	As string `yaml:"as,omitempty"`

	// Strategy controls what happens when multiple CRs match the selector.
	//   first (default) — use the first match
	//   all             — put all matches in .cross.<as>[] (array)
	Strategy string `yaml:"strategy,omitempty"`

	// Source is the fallback for cross-binary or cross-cluster observation.
	// When absent, the informer cache is used (zero API calls).
	// When set, the endpoint is called when the informer is unavailable.
	Source *CrossSource `yaml:"source,omitempty"`
}

type CrossSelector struct {
	// Name is the CR name to look up. Template expressions supported.
	//   name: "{{ .metadata.name }}"    → same name as the current CR
	Name string `yaml:"name,omitempty"`

	// Namespace is the CR namespace. Template expressions supported.
	// Default: same namespace as the current CR.
	Namespace string `yaml:"namespace,omitempty"`

	// LabelSelector selects CRs by label — for 1:N or N:1 relationships.
	//   labelSelector: "tenant={{ .spec.tenant }},env={{ .spec.environment }}"
	// When set, Name and Namespace are ignored.
	LabelSelector string `yaml:"labelSelector,omitempty"`
}

type CrossSource struct {
	// Endpoint is the URL to call when the informer is unavailable.
	// Template expressions supported.
	//   endpoint: "http://database-operator:8080/katalog/database/cr/{{ .metadata.namespace }}/{{ .metadata.name }}"
	Endpoint string `yaml:"endpoint"`

	// Token is a bearer token for the endpoint. $ENV_VAR syntax supported.
	Token string `yaml:"token,omitempty"`

	// CacheFor is how long to cache the result before calling again.
	// Default: 30s — prevents hammering the endpoint on every resync.
	CacheFor string `yaml:"cacheFor,omitempty"`
}

type DayOfWeekCondition struct {
	// In — active on these days. Full English names: Monday, Tuesday, etc.
	In []string `yaml:"in,omitempty"`

	// NotIn — active on all days except these.
	NotIn []string `yaml:"notIn,omitempty"`
}

type DeleteRequest struct {
	Object         map[string]interface{}
	Declarations   []ProviderDeclaration
	Kube           KubeReader
	Logger         zerolog.Logger
	OwnerName      string
	OwnerNamespace string
}

type DeletionProtectionConfig struct {
	// Enabled controls whether deletion protection is active.
	// Default: true when the deletionProtection block is declared.
	Enabled *bool `yaml:"enabled,omitempty"`

	// ServiceName is the Kubernetes Service fronting Orkestra's HTTPS server.
	// The API server sends webhook requests to this Service.
	// Default: ORKESTRA_SERVICE_NAME env / "orkestra".
	ServiceName string `yaml:"serviceName,omitempty"`

	// FailurePolicy controls what the API server does when Orkestra is unreachable.
	// "Fail" — reject the DELETE (recommended for protection; this is the default).
	// "Ignore" — allow the DELETE through when Orkestra cannot be reached.
	// Default: "Fail".
	FailurePolicy string `yaml:"failurePolicy,omitempty"`

	// CleanupOnShutdown controls whether Deletion protection webhook is deleted on graceful shutdown.
	// Default: false — Deletion protection webhook persists across restarts.
	CleanupOnShutdown bool `yaml:"cleanupOnShutdown,omitempty"`
}

type DependencyCondtion string

type DependsOnCondition struct {
	Condition string `yaml:"condition" json:"condition"`
}

type DependsOnMap map[string]DependsOnCondition

type DeploymentTemplateSource struct {
	// Version — OrkestraRegistry implementation version to use. Omit for latest.
	Version string `yaml:"version" json:"version,omitempty" validate:"omitempty"`

	// Name — Deployment and primary container name.
	// Supports template expressions.
	// Default when omitted: "{{ .metadata.name }}-deployment"
	Name string `yaml:"name" json:"name,omitempty" validate:"omitempty"`

	// Image — container image. Required (must be declared here or resolvable from CR).
	// Static:  "nginx:1.25"
	// Dynamic: "{{ .spec.image }}"
	Image string `yaml:"image" json:"image" validate:"omitempty"`

	// Replicas — number of pod replicas as a string.
	// Static:  "3"
	// Dynamic: "{{ .spec.replicas }}"
	// Default: "1"
	Replicas string `yaml:"replicas" json:"replicas,omitempty" validate:"omitempty"`

	// Port — primary container port as a string.
	// Static:  "8080"
	// Dynamic: "{{ .spec.port }}"
	// Omit to expose no port.
	Port string `yaml:"port" json:"port,omitempty" validate:"omitempty"`

	// Namespace — target namespace for the Deployment.
	// Default when omitted: "{{ .metadata.namespace }}" (same namespace as the CR).
	Namespace string `yaml:"namespace" json:"namespace,omitempty" validate:"omitempty"`

	// Labels — applied to the Deployment ObjectMeta and the pod template.
	// Label values support template expressions.
	// Orkestra always adds: managed-by=orkestra, orkestra-owner=<cr-name>
	Labels []ResourceLabel `yaml:"labels" json:"labels,omitempty" validate:"omitempty"`

	// Annotations — applied to the Deployment ObjectMeta only.
	// Annotation values support template expressions.
	Annotations []ResourceLabel `yaml:"annotations" json:"annotations,omitempty" validate:"omitempty"`

	// Resources — CPU and memory requests/limits for the primary container.
	// Values are static Kubernetes quantity strings.
	// Template expressions are not supported in resource quantities.
	Resources *ResourceRequirements `yaml:"resources" json:"resources,omitempty" validate:"omitempty"`

	// Env — environment variables for the primary container.
	// Keys are env var names. Values support template expressions.
	// Example:
	//   env:
	//     REGION: "{{ .item }}"
	//     DB_HOST: "{{ .cross.db.status.endpoint }}"
	//
	// If omitted, no environment variables are added.
	// Env map[string]string `yaml:"env" json:"env,omitempty" validate:"omitempty"`
	Env map[string]EnvVarSource `yaml:"env" json:"env,omitempty"`

	EnvFrom []EnvFromSource `yaml:"envFrom,omitempty" json:"envFrom,omitempty"`

	// Reconcile: true — also apply this declaration as drift correction on every
	// reconcile. Equivalent to declaring the same entry under both onCreate and
	// onReconcile. When false (default), only runs on onCreate (idempotent create).
	Reconcile bool `yaml:"reconcile" json:"reconcile,omitempty" validate:"omitempty"`

	Conditions []Condition `yaml:"when,omitempty" json:"when,omitempty"`
	// ForEach declares dynamic expansion over a list field.
	// When set, one source declaration becomes N declarations — one per list element.
	// .item and .<as> are available in template expressions within this declaration.
	ForEach *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`

	// AnyOf holds OR conditions — at least one must pass for this resource to be created.
	// Works alongside the existing Conditions (when:) field which uses AND semantics.
	AnyOf []Condition `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`

	// WorkingDirectory sets the container's working directory (container.WorkingDir).
	// Useful for Git-backed pipelines where build/test commands must run inside
	// a checked-out repository path.
	WorkingDirectory string `yaml:"workingDirectory,omitempty" json:"workingDirectory,omitempty"`
}

type DockerHookSpec struct {
	// Image is the fully-qualified image reference to build.
	//
	// Examples:
	//   "registry.example.com/webapp:{{ .git.commit }}"
	//   "ghcr.io/org/service:{{ .status.version }}"
	//
	// This field supports template expressions and is required.
	Image string `yaml:"image" json:"image"`

	// WorkingDirectory is the directory used as the Docker build context.
	//
	// In most cases this is the same as the Git hook's .git.path:
	//   workingDirectory: "{{ .git.path }}"
	//
	// If omitted, Orkestra defaults to the CR's working directory (rarely useful).
	WorkingDirectory string `yaml:"workingDirectory,omitempty" json:"workingDirectory,omitempty"`

	// Dockerfile optionally overrides the Dockerfile path.
	//
	// Examples:
	//   "Dockerfile"
	//   "deploy/Dockerfile.prod"
	//
	// When empty, Orkestra uses "Dockerfile" in the working directory.
	Dockerfile string `yaml:"dockerfile,omitempty" json:"dockerfile,omitempty"`

	// Push controls whether the built image should be pushed to the registry.
	//
	// When true:
	//   • Orkestra executes `docker push <image>` after a successful build.
	//   • Push failures are surfaced via .docker.error.
	//
	// When false:
	//   • The image is built locally only.
	Push bool `yaml:"push,omitempty" json:"push,omitempty"`

	// Builder selects the OCI build tool to use.
	//
	// Supported values: "docker" (default), "kaniko", "buildah", "podman".
	// When empty, Orkestra checks the OCI_BUILDER environment variable,
	// then falls back to "docker".
	//
	// kaniko — builds without a Docker socket; works in any Kubernetes pod.
	// buildah — rootless builds via buildah bud.
	// podman  — local builds via podman build.
	Builder string `yaml:"builder,omitempty" json:"builder,omitempty"`

	// Reconcile controls whether this Docker hook runs on every reconcile.
	//
	// When true:
	//   • Docker build/push runs on every reconcile cycle.
	//   • Useful for Git-driven pipelines where .git.changed triggers rebuilds.
	//
	// When false:
	//   • Docker build/push runs only during onCreate.
	//   • Useful for one-time initialization images.
	Reconcile bool `yaml:"reconcile,omitempty" json:"reconcile,omitempty"`

	// ContinueOnError controls behaviour when the Docker build or push fails.
	//
	// false (default) — Docker failure returns an error and halts reconciliation.
	// true            — Docker failure injects .docker.error but reconciliation continues.
	ContinueOnError bool `yaml:"continueOnError,omitempty" json:"continueOnError,omitempty"`

	// When is an optional list of conditions that must all pass before
	// this field is written. If absent or empty, the field is always written.
	//
	// All conditions are AND-ed together.
	// To express OR logic, declare multiple StatusField entries for the same path.
	//
	// Conditions are evaluated against the full CR object map — the same
	// map available to template expressions. This means .status.phase,
	// .spec.image, .children.job.status.succeeded are all accessible.
	When []Condition `yaml:"when,omitempty"`

	AnyOf []Condition `yaml:"anyOf,omitempty"`
}

type Duration struct {
	time.Duration
}

type EndpointsConfig struct {
	// Enabled if false disables all endpoints for this CRD
	// Default is true
	Enabled *bool `yaml:"enabled" json:"enabled,omitempty"`

	// Health controls whether the /health endpoint is served.
	Health *bool `yaml:"health" json:"health,omitempty"`

	// Info controls whether the /info endpoint is served.
	Info *bool `yaml:"info" json:"info,omitempty"`
}

type EnrichmentOutcome int

type EnvFromSource struct {
	ConfigMapRef string `yaml:"configMapRef,omitempty" json:"configMapRef,omitempty"`
	SecretRef    string `yaml:"secretRef,omitempty" json:"secretRef,omitempty"`
}

type EnvVarSource struct {
	Value           string           `yaml:"value,omitempty" json:"value,omitempty"`
	SecretKeyRef    *SecretKeyRef    `yaml:"secretKeyRef,omitempty" json:"secretKeyRef,omitempty"`
	ConfigMapKeyRef *ConfigMapKeyRef `yaml:"configMapKeyRef,omitempty" json:"configMapKeyRef,omitempty"`
}

type ExternalCallResult struct {
	// Status is the HTTP status code as a string ("200", "404", "503").
	// Empty string when the call failed before receiving a response.
	Status string `json:"status"`

	// Body is the first 4096 bytes of the response body.
	// Truncated to avoid unbounded memory use.
	Body string `json:"body"`

	// Error is the error message when the call failed.
	// Empty on success.
	Error string `json:"error"`

	// Called is "true" when the call was made, "false" when skipped (conditions failed).
	Called string `json:"called"`

	// Additional values for metrics
	StatusCode      int     `json:"statusCode"`
	DurationSeconds float64 `json:"durationSeconds"`
}

type ExternalCallSpec struct {
	// Name is the identifier used to access the result in template expressions.
	//   name: health-check → {{ .external.health-check.status }}
	Name string `yaml:"name"`

	// URL is the endpoint to call. Template expressions are supported.
	//   url: "{{ .spec.serviceUrl }}/health"
	//   url: "https://api.example.com/resources/{{ .metadata.name }}"
	URL string `yaml:"url"`

	// Method is the HTTP method. Default: GET.
	Method string `yaml:"method,omitempty"`

	// Body is the request body for POST/PUT/PATCH requests.
	// Template expressions supported.
	//   body: '{"name": "{{ .metadata.name }}"}'
	Body string `yaml:"body,omitempty"`

	// Token is a bearer token for Authorization header.
	// Use $ENV_VAR syntax to reference environment variables:
	//   token: "$API_TOKEN"
	Token string `yaml:"token,omitempty"`

	// Headers are additional HTTP headers to include.
	Headers map[string]string `yaml:"headers,omitempty"`

	// Timeout is the maximum duration for this call.
	// Default: 10s. Format: "5s", "1m", "500ms"
	Timeout string `yaml:"timeout,omitempty"`

	// ExpectedStatus is the HTTP status code that signals success.
	// Default: any 2xx status.
	// When set to 200, any non-200 response is treated as a failure.
	ExpectedStatus int `yaml:"expectedStatus,omitempty"`

	// ContinueOnError controls whether a failed call halts reconciliation.
	// false (default): a call failure returns an error, halting the reconcile.
	// true:            failure is logged, result has error set, reconcile continues.
	//
	// Use true for optional calls: notifications, metrics, feature flags.
	// Use false (default) for required calls: health checks, dependency readiness.
	ContinueOnError bool `yaml:"continueOnError,omitempty"`

	// When conditions gate this call — if conditions fail, the call is skipped.
	// The result is not injected when skipped.
	Conditions []Condition `yaml:"when,omitempty"`
	AnyOf      []Condition `yaml:"anyOf,omitempty"`
}

type FileSource struct {
	// URL or path — the file to load.
	// May be a local path, an HTTP(S) URL, or an $ENV_VAR reference.
	URL string `yaml:"url"`

	// Auth — optional authentication for remote sources.
	// Ignored for local paths.
	Auth *FileSourceAuth `yaml:"auth,omitempty"`
}

type FileSourceAuth struct {
	// Type — authentication scheme.
	// Supported values: "bearer", "github", "basic"
	Type string `yaml:"type" validate:"required,oneof=bearer github basic"`

	// FromEnv — environment variable containing the bearer token or GitHub token.
	// Used when Type is "bearer" or "github".
	FromEnv string `yaml:"fromEnv,omitempty"`

	// UsernameFromEnv — environment variable containing the username.
	// Used when Type is "basic".
	UsernameFromEnv string `yaml:"usernameFromEnv,omitempty"`

	// PasswordFromEnv — environment variable containing the password.
	// Used when Type is "basic".
	PasswordFromEnv string `yaml:"passwordFromEnv,omitempty"`
}

type ForEachSpec struct {
	// Field is the dot-notation path to a list or map field on the CR.
	//
	// List field → one item per element:
	//   field: spec.regions  → ["us-east-1", "eu-west-1"]
	//   .item = element value ("us-east-1")
	//
	// Map field → one item per key (sorted alphabetically):
	//   field: spec.regions  → {us-east-1: {replicas: 3}, eu-west-1: {replicas: 1}}
	//   .item = map key ("us-east-1"), .value = map value ({replicas: 3})
	//   .value.replicas = "3"
	Field string `yaml:"field"`

	// As is the name used to access the current item in template expressions.
	// Default: "item" — {{ .item }}
	// When set: both {{ .item }} and {{ .<as> }} work.
	//   as: region → {{ .region }} and {{ .item }} both resolve to the current element
	As string `yaml:"as,omitempty"`
}

type GitHookSpec struct {
	// Repo is the Git repository URL.
	Repo string `yaml:"repo" json:"repo"`

	// Branch is the branch to track. Default: "main".
	Branch string `yaml:"branch,omitempty" json:"branch,omitempty"`

	// Path optionally scopes change detection to a subdirectory.
	Path string `yaml:"path,omitempty" json:"path,omitempty"`

	// Reconcile controls whether this Git hook runs on every reconcile.
	//
	// When true:
	//   • Git fetch runs on every reconcile cycle.
	//   • `.git.changed` is updated accordingly.
	//
	// When false:
	//   • Git runs only on onCreate.
	//   • Useful for one-time initialization.
	Reconcile bool `yaml:"reconcile,omitempty" json:"reconcile,omitempty"`

	// ContinueOnError controls behaviour when the Git operation fails.
	//
	// false (default) — Git failure returns an error and halts reconciliation.
	// true            — Git failure injects .git.error but reconciliation continues.
	//                   Subsequent when: conditions on git.changed will not fire.
	ContinueOnError bool `yaml:"continueOnError,omitempty" json:"continueOnError,omitempty"`

	// When is an optional list of conditions that must all pass before
	// this field is written. If absent or empty, the field is always written.
	//
	// All conditions are AND-ed together.
	// To express OR logic, declare multiple StatusField entries for the same path.
	//
	// Conditions are evaluated against the full CR object map — the same
	// map available to template expressions. This means .status.phase,
	// .spec.image, .children.job.status.succeeded are all accessible.
	When []Condition `yaml:"when,omitempty"`

	AnyOf []Condition `yaml:"anyOf,omitempty"`
}

type HPATemplateSource struct {
	Version string `yaml:"version" json:"version,omitempty"`

	// Name — HPA resource name. Default: "{{ .metadata.name }}-hpa"
	Name string `yaml:"name" json:"name,omitempty"`

	// Namespace — target namespace. Default: CR namespace.
	Namespace string `yaml:"namespace" json:"namespace,omitempty"`

	// ScaleTargetRef — the target workload this HPA scales.
	// Supports Deployment, ReplicaSet, StatefulSet, or any scalable resource.
	// Supports template expressions: "{{ .metadata.name }}"
	ScaleTargetRef ScaleTargetRef `yaml:"scaleTargetRef" json:"scaleTargetRef,omitempty"`

	// MinReplicas — minimum replica count as a string. Supports template expressions.
	MinReplicas string `yaml:"minReplicas" json:"minReplicas,omitempty"`

	// MaxReplicas — maximum replica count as a string. Supports template expressions.
	MaxReplicas string `yaml:"maxReplicas" json:"maxReplicas,omitempty"`

	// TargetCPUUtilizationPercentage — CPU utilization target (0-100). Supports templates.
	TargetCPUUtilizationPercentage string `yaml:"targetCPUUtilizationPercentage" json:"targetCPUUtilizationPercentage,omitempty"`

	// Labels applied to HPA metadata. Values support template expressions.
	Labels []ResourceLabel `yaml:"labels" json:"labels,omitempty"`

	Reconcile  bool         `yaml:"reconcile" json:"reconcile,omitempty"`
	Conditions []Condition  `yaml:"when,omitempty" json:"when,omitempty"`
	AnyOf      []Condition  `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`
	ForEach    *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`
}

type HelmSource struct {
	// Repo — Helm repository URL.
	// e.g. "https://charts.myorg.io"
	Repo string `yaml:"repo" validate:"required"`

	// Chart — chart name within the repository.
	// e.g. "platform-crds"
	Chart string `yaml:"chart" validate:"required"`

	// Version — chart version to use. Required for reproducibility.
	// And also used as git ref
	// e.g. "1.2.0"
	Version string `yaml:"version" validate:"required"`

	// Path — chart path within git repo
	Path string `yaml:"path"       validate:"omitempty"`

	// ValueFiles — list of values files to apply when rendering the chart.
	// Each entry can be a local path or a remote URL.
	// Supports environment variable references: $MY_VALUES_FILE
	// Applied in order — later files override earlier ones (same as helm -f).
	ValueFiles []string `yaml:"valueFiles,omitempty"`

	// Values — inline key-value pairs applied after valueFiles.
	// Same as helm --set key=value.
	Values map[string]interface{} `yaml:"values,omitempty"`
}

type HookDeclaration struct {
	// Location — fully qualified Go import path. Local or remote module.
	// e.g. "github.com/myorg/hooks" or "github.com/orkspace/orkestra/pkg/reconciler/hooks"
	Location string `yaml:"location" json:"location" validate:"required"`

	// Function — exported function name at Location that returns hooks.
	// e.g. "ProjectHooks"
	Function string `yaml:"function" json:"function" validate:"required"`

	// Alias — Go import alias. Optional, auto-derived from Location if omitted.
	// e.g. "projecthooks"
	Alias string `yaml:"alias" json:"alias,omitempty" validate:"omitempty"`
}

type HookTemplates struct {
	Deployments              []DeploymentTemplateSource     `yaml:"deployments" json:"deployments,omitempty" validate:"omitempty"`
	ReplicaSets              []ReplicaSetTemplateSource     `yaml:"replicaSets" json:"replicaSets,omitempty" validate:"omitempty"`
	Services                 []ServiceTemplateSource        `yaml:"services" json:"services,omitempty" validate:"omitempty"`
	Pods                     []PodTemplateSource            `yaml:"pods" json:"pods,omitempty" validate:"omitempty"`
	Jobs                     []JobTemplateSource            `yaml:"jobs" json:"jobs,omitempty" validate:"omitempty"`
	CronJobs                 []CronJobTemplateSource        `yaml:"cronJobs" json:"cronJobs,omitempty" validate:"omitempty"`
	Secrets                  []SecretTemplateSource         `yaml:"secrets" json:"secrets,omitempty" validate:"omitempty"`
	ConfigMaps               []ConfigMapTemplateSource      `yaml:"configMaps" json:"configMaps,omitempty" validate:"omitempty"`
	ServiceAccounts          []ServiceAccountTemplateSource `yaml:"serviceAccounts" json:"serviceAccounts,omitempty" validate:"omitempty"`
	StatefulSets             []StatefulSetTemplateSource    `yaml:"statefulSets" json:"statefulSets,omitempty" validate:"omitempty"`
	Ingresses                []IngressTemplateSource        `yaml:"ingresses" json:"ingresses,omitempty" validate:"omitempty"`
	PersistentVolumes        []PVTemplateSource             `yaml:"persistentVolumes" json:"persistentVolumes,omitempty" validate:"omitempty"`
	PersistentVolumeClaims   []PVCTemplateSource            `yaml:"persistentVolumeClaims" json:"persistentVolumeClaims,omitempty" validate:"omitempty"`
	HorizontalPodAutoscalers []HPATemplateSource            `yaml:"hpa" json:"hpa,omitempty" validate:"omitempty"`
	PodDisruptionBudgets     []PDBTemplateSource            `yaml:"pdb" json:"pdb,omitempty" validate:"omitempty"`
	Namespaces               []NamespaceTemplateSource      `yaml:"namespaces" json:"namespaces,omitempty" validate:"omitempty"`

	// External declares HTTP calls to make before resource creation.
	// Results available as .external.<n>.status, .body, .error
	External []ExternalCallSpec `yaml:"external,omitempty" json:"external,omitempty"`

	// Git declares optional Git-backed reconcile behaviour for this CRD.
	//
	// When configured, Orkestra:
	//   - Maintains a local working copy of the repository.
	//   - Periodically checks the target branch for new commits.
	//   - Enqueues reconciles for all CRs of this type when the branch tip changes.
	//
	// This enables declarative, in-cluster CI/CD pipelines where Git acts
	// as the source of pipeline logic and the CRs provide parameters.
	//
	// When omitted, reconcile behaviour is unchanged and no Git traffic
	// is generated for this CRD.
	Git *GitHookSpec `yaml:"git,omitempty" json:"git,omitempty"`

	// Docker declares optional Docker-backed reconcile behaviour for this CRD.
	//
	// When configured
	//	- Builds and optionally pushes a docker image
	Docker *DockerHookSpec `yaml:"docker,omitempty" json:"docker,omitempty"`

	// Ordered controls whether deletion happens sequentially with verification.
	// true  — delete groups in order, verify each is gone before proceeding
	// false — delete all resources via owner references (default, parallel)
	Ordered bool `yaml:"ordered,omitempty" json:"ordered,omitempty"`

	// Groups declares sequential deletion stages for ordered deletes.
	// Each element is a full HookTemplates block whose resources are deleted
	// as a unit. Orkestra deletes stage N, waits until all resources are gone,
	// then deletes stage N+1. Omit when Ordered is false.
	// When Ordered is true and Groups is empty, the flat resource fields above
	// (Jobs, Deployments, …) are treated as a single implicit group.
	Groups []HookTemplates `yaml:"groups,omitempty" json:"groups,omitempty"`

	// Timeout is the maximum time to wait for each deletion group to complete.
	// Defaults to 5m when Ordered is true. Ignored when Ordered is false.
	Timeout *Duration `yaml:"timeout,omitempty" json:"timeout,omitempty"`

	// TODO with placeholer
	Volumes                     []PlaceholderSource `yaml:"volumes" json:"volumes,omitempty" validate:"omitempty"`
	VolumeMounts                []PlaceholderSource `yaml:"volumeMounts" json:"volumeMounts,omitempty" validate:"omitempty"`
	Roles                       []PlaceholderSource `yaml:"roles" json:"roles,omitempty" validate:"omitempty"`
	RoleBindings                []PlaceholderSource `yaml:"roleBindings" json:"roleBindings,omitempty" validate:"omitempty"`
	ClusterRoles                []PlaceholderSource `yaml:"clusterRoles" json:"clusterRoles,omitempty" validate:"omitempty"`
	ClusterRoleBindings         []PlaceholderSource `yaml:"clusterRoleBindings" json:"clusterRoleBindings,omitempty" validate:"omitempty"`
	ServiceMonitors             []PlaceholderSource `yaml:"serviceMonitors" json:"serviceMonitors,omitempty" validate:"omitempty"`
	PodSecurityPolicies         []PlaceholderSource `yaml:"podSecurityPolicies" json:"podSecurityPolicies,omitempty" validate:"omitempty"`
	PriorityClasses             []PlaceholderSource `yaml:"priorityClasses" json:"priorityClasses,omitempty" validate:"omitempty"`
	LimitRanges                 []PlaceholderSource `yaml:"limitRanges" json:"limitRanges,omitempty" validate:"omitempty"`
	ResourceQuotas              []PlaceholderSource `yaml:"resourceQuotas" json:"resourceQuotas,omitempty" validate:"omitempty"`
	RuntimeClasses              []PlaceholderSource `yaml:"runtimeClasses" json:"runtimeClasses,omitempty" validate:"omitempty"`
	PriorityLevelConfigurations []PlaceholderSource `yaml:"priorityLevelConfigurations" json:"priorityLevelConfigurations,omitempty" validate:"omitempty"`
	PodTemplates                []PlaceholderSource `yaml:"podTemplates" json:"podTemplates,omitempty" validate:"omitempty"`
	DaemonSets                  []PlaceholderSource `yaml:"daemonSets" json:"daemonSets,omitempty" validate:"omitempty"`
	NetworkPolicies             []PlaceholderSource `yaml:"networkPolicies" json:"networkPolicies,omitempty" validate:"omitempty"`

	// Storage
	StorageClasses   []PlaceholderSource `yaml:"storageClasses" json:"storageClasses,omitempty" validate:"omitempty"`
	StorageLocations []PlaceholderSource `yaml:"storageLocations" json:"storageLocations,omitempty" validate:"omitempty"`
	StoragePools     []PlaceholderSource `yaml:"storagePools" json:"storagePools,omitempty" validate:"omitempty"`
	StorageBackups   []PlaceholderSource `yaml:"storageBackups" json:"storageBackups,omitempty" validate:"omitempty"`
	StorageSnapshots []PlaceholderSource `yaml:"storageSnapshots" json:"storageSnapshots,omitempty" validate:"omitempty"`
	StorageVolumes   []PlaceholderSource `yaml:"storageVolumes" json:"storageVolumes,omitempty" validate:"omitempty"`
}

type IngressTLSSpec struct {
	// Enabled — when true, create a TLS secret and populate ingress.spec.tls.
	Enabled bool `yaml:"enabled" json:"enabled,omitempty"`

	// SecretName — name of the TLS secret. Supports template expressions.
	// Default: "{{ .metadata.name }}-tls"
	SecretName string `yaml:"secretName" json:"secretName,omitempty"`

	// Hosts — list of hostnames to include in the TLS certificate SANs.
	// Each element supports template expressions.
	Hosts []string `yaml:"hosts" json:"hosts,omitempty"`

	// ValidFor — certificate validity duration (e.g. "1y", "90d"). Default: "1y".
	ValidFor string `yaml:"validFor" json:"validFor,omitempty"`
}

type IngressTemplateSource struct {
	Version string `yaml:"version" json:"version,omitempty"`

	// Name — Ingress resource name. Default: "{{ .metadata.name }}-ingress"
	Name string `yaml:"name" json:"name,omitempty"`

	// Namespace — target namespace. Default: CR namespace.
	Namespace string `yaml:"namespace" json:"namespace,omitempty"`

	// Host — virtual host name for the Ingress rule.
	Host string `yaml:"host" json:"host,omitempty"`

	// ServiceName — backend Service name this Ingress routes to.
	ServiceName string `yaml:"serviceName" json:"serviceName,omitempty"`

	// ServicePort — backend Service port as a string. Supports template expressions.
	ServicePort string `yaml:"servicePort" json:"servicePort,omitempty"`

	// Path — HTTP path prefix. Default: "/"
	Path string `yaml:"path" json:"path,omitempty"`

	// PathType — Kubernetes IngressPathType: Prefix, Exact, ImplementationSpecific.
	// Default: Prefix.
	PathType string `yaml:"pathType" json:"pathType,omitempty"`

	// IngressClass — Ingress class name (nginx, traefik, etc.). Optional.
	IngressClass string `yaml:"ingressClass" json:"ingressClass,omitempty"`

	// Labels applied to Ingress metadata. Values support template expressions.
	Labels []ResourceLabel `yaml:"labels" json:"labels,omitempty"`

	// Annotations applied to Ingress metadata. Values support template expressions.
	Annotations []ResourceLabel `yaml:"annotations" json:"annotations,omitempty"`

	// TLS — optional TLS configuration. When tls.enabled is true, Orkestra
	// generates a self-signed TLS Secret before creating the Ingress.
	TLS *IngressTLSSpec `yaml:"tls" json:"tls,omitempty"`

	Reconcile  bool         `yaml:"reconcile" json:"reconcile,omitempty"`
	Conditions []Condition  `yaml:"when,omitempty" json:"when,omitempty"`
	AnyOf      []Condition  `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`
	ForEach    *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`
}

type JobTemplateSource struct {
	// Version — OrkestraRegistry implementation version. Omit for latest.
	Version string `yaml:"version" json:"version,omitempty" validate:"omitempty"`

	// Name — Job name.
	// Default when omitted: "{{ .metadata.name }}-job"
	Name string `yaml:"name" json:"name,omitempty" validate:"omitempty"`

	// Image — container image. Required.
	Image string `yaml:"image" json:"image" validate:"omitempty"`

	// Command — container entrypoint command.
	// Each element is resolved independently — template expressions are supported per element.
	// e.g. ["sh", "-c", "echo cleaning up {{ .metadata.name }}"]
	Command []string `yaml:"command" json:"command,omitempty" validate:"omitempty"`

	// Args — arguments passed to the container command.
	// Each element supports template expressions independently.
	Args []string `yaml:"args" json:"args,omitempty" validate:"omitempty"`

	// BackoffLimit — number of Pod restart attempts before the Job is marked Failed.
	// Default: 3.
	BackoffLimit int `yaml:"backoffLimit" json:"backoffLimit,omitempty" validate:"omitempty"`

	// Namespace — target namespace.
	// Default when omitted: "{{ .metadata.namespace }}"
	Namespace string `yaml:"namespace" json:"namespace,omitempty" validate:"omitempty"`

	// Labels — applied to Job metadata. Values support template expressions.
	Labels []ResourceLabel `yaml:"labels" json:"labels,omitempty" validate:"omitempty"`

	Conditions []Condition `yaml:"when,omitempty" json:"when,omitempty"`

	// Reconcile: true — also apply this declaration as drift correction on every
	// reconcile. Equivalent to declaring the same entry under both onCreate and
	// onReconcile. When false (default), only runs on onCreate (idempotent create).
	Reconcile bool `yaml:"reconcile" json:"reconcile,omitempty" validate:"omitempty"`

	// ForEach declares dynamic expansion over a list field.
	// When set, one source declaration becomes N declarations — one per list element.
	// .item and .<as> are available in template expressions within this declaration.
	ForEach *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`

	// AnyOf holds OR conditions — at least one must pass for this resource to be created.
	// Works alongside the existing Conditions (when:) field which uses AND semantics.
	AnyOf []Condition `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`

	// WorkingDirectory sets the container's working directory (container.WorkingDir).
	// Useful for Git-backed pipelines where build/test commands must run inside
	// a checked-out repository path.
	WorkingDirectory string `yaml:"workingDirectory,omitempty" json:"workingDirectory,omitempty"`
}

type KatalogFile struct {
	APIVersion string          `yaml:"apiVersion"`
	Kind       string          `yaml:"kind"`
	Metadata   KatalogMeta     `yaml:"metadata"`
	Anchors    map[string]any  `yaml:"anchors,omitempty"`
	Sources    *KatalogSources `yaml:"sources,omitempty"`
	Spec       KatalogSpec     `yaml:"spec"`
	Security   KatalogSecurity `yaml:"security"`

	// Providers declares which external provider libraries this Katalog requires.
	// Top-level alongside spec: and security: — providers represent a distinct
	// operational concern (infrastructure dependencies) separate from CRD definitions.
	//
	//   providers:
	//     - name: aws
	//       required: true
	//       auth:
	//         accessKeyId: "$AWS_ACCESS_KEY_ID"
	//         secretAccessKey: "$AWS_SECRET_ACCESS_KEY"
	//         region: "$AWS_REGION"
	//     - name: mongodb
	//       required: true
	//       auth:
	//         mongoUri: "$MONGODB_URL"
	Providers []KatalogProviderRequirement `yaml:"providers,omitempty"`
}

type KatalogForUI struct {
	APIVersion string                       `json:"apiVersion"`          // Orkestra API version
	Kind       string                       `json:"kind"`                // Always "Katalog" at runtime
	Metadata   KatalogMeta                  `json:"metadata"`            // Katalog metadata (name, description, etc.)
	Spec       KatalogSpecForUI             `json:"spec"`                // CRD definitions
	Security   KatalogSecurity              `json:"security"`            // Security settings
	Providers  []KatalogProviderRequirement `json:"providers,omitempty"` // Provider requirements
}

type KatalogMeta struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description,omitempty"`
	Version     string `yaml:"version,omitempty"`
	Author      string `yaml:"author,omitempty"`
	License     string `yaml:"license,omitempty"`
}

type KatalogNotification struct {
	// Enabled gates all notification dispatch. Default: true when the
	// notification: block is declared. Set false to silence all channels
	// without removing the configuration.
	Enabled *bool `yaml:"enabled,omitempty"`

	// Defaults defines global notification behavior applied when a team does
	// not specify its own override.
	Defaults *NotificationDefaults `yaml:"defaults,omitempty"`

	// Teams declares named notification targets. Conditions and rollback blocks
	// reference teams by name via notify: ["platform", "oncall"].
	Teams map[string]*NotificationTeam `yaml:"teams,omitempty"`
}

type KatalogProviderRequirement struct {
	// Name is the YAML block key used under operatorBox.providers.
	// Must match the Name() return value of the registered Provider.
	// e.g. "aws", "mongodb", "stripe"
	Name string `yaml:"name"`

	// Required controls whether `ork validate` hard-fails on missing registration.
	// true  → validation error if not registered (operator will not function correctly)
	// false → validation warning only (provider blocks are skipped at runtime)
	Required bool `yaml:"required"`

	// Auth holds the provider credentials. Values support $ENV_VAR expansion —
	// use "$MY_SECRET" and Orkestra will substitute os.Getenv("MY_SECRET") at startup.
	//
	// AWS example:
	//   auth:
	//     accessKeyId: "$AWS_ACCESS_KEY_ID"
	//     secretAccessKey: "$AWS_SECRET_ACCESS_KEY"
	//     region: "us-east-1"
	//
	// MongoDB example:
	//   auth:
	//     mongoUri: "$MONGODB_URL"
	Auth map[string]string `yaml:"auth,omitempty"`

	// Version is the expected provider library version.
	// Used by `ork provider install` to pull the correct OCI artifact.
	// Optional — if absent, the latest version is used.
	Version string `yaml:"version,omitempty"`

	// Library is the OCI artifact reference for this provider.
	// e.g. "oci://registry.orkestra.io/providers/aws:1.8.0"
	// Used by `ork provider install`. Optional for locally registered providers.
	Library string `yaml:"library,omitempty"`
}

type KatalogSecurity struct {
	// DeletionProtection controls whether Orkestra registers a webhook that
	// blocks deletion of its managed CRDs, deployment, service, etc.
	//
	// When enabled (default when block is present):
	//   - Registers /deletion-protection endpoint on the HTTPS server
	//   - Creates ValidatingWebhookConfiguration "orkestra-delete-protection"
	//   - Entry 1: broad rule for CRDs; handler filters by ProtectedCRDNames()
	//   - Entry 2: ObjectSelector-gated rule for deployment, service, etc
	//
	// To decommission an operator with deletion protection:
	//   1. Set enabled: false
	//   2. Redeploy Orkestra (webhook removed on startup)
	//   3. Delete resources normally
	//
	// nil pointer: not enabled (not declared in YAML).
	DeletionProtection *DeletionProtectionConfig `yaml:"deletionProtection,omitempty"`

	// Webhooks controls the admission webhook settings (ValidatingWebhookConfiguration,
	// MutatingWebhookConfiguration). These apply globally — there is no per-CRD switch.
	// CRDs declare validation/mutation rules; the webhook is enabled or not globally.
	//
	// nil pointer: admission webhooks not configured; ENV vars drive behavior.
	Webhooks *WebhooksConfig `yaml:"webhooks,omitempty"`

	// Conversion controls the /convert endpoint and CRD version conversion.
	// Separate from admission webhooks — conversion has its own endpoint and
	// configuration (window size for stats, etc.).
	//
	// nil pointer: conversion not configured; ENV vars drive behavior.
	Conversion *ConversionConfig `yaml:"conversion,omitempty"`

	// NamespaceProtection controls the optional validating webhook that prevents
	// Orkestra-managed CRs from being created or updated in forbidden namespaces.
	//
	// This is an admission-time safeguard only. When enabled:
	//   - Registers /namespace-protection endpoint on the HTTPS server
	//   - Creates ValidatingWebhookConfiguration "orkestra-namespace-protection"
	//   - Enforces allowedNamespaces / restrictedNamespaces declared by each CRD
	//
	// If disabled or omitted, namespace rules are not enforced at apply time.
	// Existing CRs in forbidden namespaces will still be reconciled normally.
	//
	// nil pointer: namespace protection not configured; ENV vars drive behavior.
	NamespaceProtection *NamespaceProtectionConfig `yaml:"namespaceProtection,omitempty"`
}

type KatalogSources struct {
	// Files — local paths, remote URLs, or environment variable references.
	// Each entry must be a valid Katalog YAML (apiVersion, kind, spec.crds).
	// Supports environment variable references: $MY_KATALOG_URL
	//
	// Simple form: just a path string (no auth)
	//   files:
	//     - ./katalogs/project.yaml
	//     - https://public.url/katalog.yaml
	//     - $MY_KATALOG_URL
	//
	// Authenticated form: a FileSource struct with auth block
	//   files:
	//     - url: https://private.url/katalog.yaml
	//       auth:
	//         type: bearer
	//         fromEnv: MY_TOKEN
	Files []FileSource `yaml:"files,omitempty"`

	// Helm — Helm chart sources. Each chart is rendered with the provided
	// value files and the resulting Katalog templates are extracted and merged.
	Helm []HelmSource `yaml:"helm,omitempty"`

	// Registry - Registry sources.
	Registry []RegistrySource `yaml:"registry,omitempty"`
}

type KatalogSpec struct {
	// Finalizers — Katalog-level finalizers applied to all CRDs
	// unless overridden at the CRD level.
	Finalizers []string `yaml:"finalizers,omitempty"`

	// CRDs — the CRD entries managed by this Orkestra instance.
	// Map key is the CRD name; Name field is injected from the key during loading.
	CRDs map[string]CRDEntry `yaml:"crds"`
}

type KatalogSpecForUI struct {
	CRDs map[string]CRDEntry `json:"crds"` // Map of CRD name to CRD definition
}

type KubeReader interface {
	// GetSecret reads a Secret's data by name in the given namespace.
	// Returns the decoded data map (base64 already decoded).
	GetSecret(ctx context.Context, namespace, name string) (map[string][]byte, error)

	// GetConfigMap reads a ConfigMap's data by name in the given namespace.
	GetConfigMap(ctx context.Context, namespace, name string) (map[string]string, error)
}

type MutationConfig struct {
	// Rules — applied in declaration order.
	Rules []MutationRule `yaml:"rules,omitempty" json:"rules,omitempty"`

	// MutateFirst — when true, mutation runs before validation at reconcile
	// time. Default false (validate first, then mutate valid objects).
	//
	// At admission time, mutation always runs first — this mirrors the
	// Kubernetes webhook ordering (MutatingWebhookConfiguration fires before
	// ValidatingWebhookConfiguration). This field only affects reconcile ordering.
	MutateFirst bool `yaml:"mutateFirst,omitempty" json:"mutateFirst,omitempty"`
}

type MutationRule struct {
	// Field — dot-notation path to the CR field to mutate.
	Field string `yaml:"field" json:"field" validate:"required"`

	// Default — set only if the field is absent or empty.
	// Supports template expressions.
	Default interface{} `yaml:"default,omitempty"` // accepts int, bool, string from YAML

	// Override — always set, regardless of current value.
	// Supports template expressions.
	Override interface{} `yaml:"override,omitempty"` // accepts int, bool, string from YAML

	// Value type
	ValueType string `yaml:"valueType,omitempty"` // "string", "int" or "integer", "float" or "number", "bool" or "boolean"
}

type NamespaceProtectionConfig struct {
	// Enabled controls whether namespace protection is active.
	// Default: true when the namespaceProtection block is declared.
	Enabled *bool `yaml:"enabled,omitempty"`

	// ServiceName is the Kubernetes Service fronting Orkestra's HTTPS server.
	// The API server sends webhook requests to this Service.
	// Default: ORKESTRA_SERVICE_NAME env / "orkestra".
	ServiceName string `yaml:"serviceName,omitempty"`

	// FailurePolicy controls what the API server does when Orkestra is unreachable.
	// "Fail"   — reject the CREATE/UPDATE (recommended; this is the default).
	// "Ignore" — allow the request through when Orkestra cannot be reached.
	// Default: "Fail".
	FailurePolicy string `yaml:"failurePolicy,omitempty"`

	// RestrictedNamespaces — deny-list applied to every CRD in this Katalog.
	// Merged additively with per-CRD restrictedNamespaces — more specific levels
	// add to, not replace, broader levels.
	RestrictedNamespaces RestrictedNamespaces `yaml:"restrictedNamespaces,omitempty" json:"restrictedNamespaces,omitempty"`

	// AllowedNamespaces — allow-list applied to every CRD in this Katalog.
	// Merged additively with per-CRD allowedNamespaces.
	AllowedNamespaces AllowedNamespaces `yaml:"allowedNamespaces,omitempty" json:"allowedNamespaces,omitempty"`

	// CleanupOnShutdown controls whether Namespace protection webhook is deleted on graceful shutdown.
	// Default: false — Namespace protection webhook persists across restarts.
	CleanupOnShutdown bool `yaml:"cleanupOnShutdown,omitempty"`
}

type NamespaceTemplateSource struct {
	// Version — OrkestraRegistry implementation version. Omit for latest.
	Version string `yaml:"version" json:"version,omitempty" validate:"omitempty"`

	// Name — ServiceAccount name.
	// Default when omitted: "{{ .metadata.name }}-sa"
	Name string `yaml:"name" json:"name,omitempty" validate:"omitempty"`

	Finalizers []string `yaml:"finalizers" json:"finalizers,omitempty" validate:"omitempty"`

	// Labels — applied to ServiceAccount metadata. Values support template expressions.
	Labels []ResourceLabel `yaml:"labels" json:"labels,omitempty" validate:"omitempty"`

	Conditions []Condition `yaml:"when,omitempty" json:"when,omitempty"`

	// Reconcile: true — also apply this declaration as drift correction on every
	// reconcile. Equivalent to declaring the same entry under both onCreate and
	// onReconcile. When false (default), only runs on onCreate (idempotent create).
	Reconcile bool `yaml:"reconcile" json:"reconcile,omitempty" validate:"omitempty"`

	// ForEach declares dynamic expansion over a list field.
	// When set, one source declaration becomes N declarations — one per list element.
	// .item and .<as> are available in template expressions within this declaration.
	ForEach *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`

	// AnyOf holds OR conditions — at least one must pass for this resource to be created.
	// Works alongside the existing Conditions (when:) field which uses AND semantics.
	AnyOf []Condition `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`
}

type NewReconcilerFunc func(
	kube *kubeclient.Kubeclient,
	inf cache.SharedIndexInformer,
	ev *event.Event,
) domain.Reconciler

type NormalizeConfig struct {
	// Spec contains field-level normalization templates.
	// Example:
	//
	//   normalize:
	//     spec:
	//       schedule: >
	//         {{ if typeMap .spec.schedule }}
	//           {{ cronFromMap .spec.schedule }}
	//         {{ else }}
	//           {{ cronNormalize .spec.schedule }}
	//         {{ end }}
	//
	// Spec maps a dot-notation field path to a template expression.
	// The template sees the raw CR (before any normalization of other fields).
	// Results are coerced to the appropriate Go type via YAML parsing:
	//   "3"     → int
	//   "true"  → bool
	//   "*/5 * * * *" → string
	// Empty result ("") sets the field to empty string — not nil.
	Spec map[string]string `yaml:"spec,omitempty"`
}

type NotificationDefaults struct {
	// Interval is the minimum time between notifications for the same
	// condition+team pair while the condition remains true. Default: 15m.
	Interval Duration `yaml:"interval,omitempty"`

	// SlackWebhookUrl is the global default Slack incoming webhook URL.
	// Used when a team declares slack: channels but no slackWebhookUrl.
	// Can be overridden per team.
	SlackWebhookUrl string `yaml:"slackWebhookUrl,omitempty"`
}

type NotificationTeam struct {
	// Email is the list of email recipients. SMTP config comes from pkg/konfig
	// env vars (SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM).
	Email []string `yaml:"email,omitempty"`

	// Slack is the list of Slack channels to notify (e.g. "#platform-alerts").
	// Requires SlackWebhookUrl (team or global default) to be configured.
	Slack []string `yaml:"slack,omitempty"`

	// SlackWebhookUrl is the incoming webhook URL for this team's Slack workspace.
	// Overrides notification.defaults.slackWebhookUrl for this team.
	// Required when Slack is non-empty and no global default is set.
	SlackWebhookUrl string `yaml:"slackWebhookUrl,omitempty"`

	// Interval overrides the global default for this team. Zero duration falls
	// back to notification.defaults.interval or the built-in default of 15m.
	Interval Duration `yaml:"interval,omitempty"`

	// Message is a Go template expression evaluated against the full resolver
	// data (.spec.*, .metadata.*, .status.*, .children.*, metrics.*).
	// When empty, Orkestra uses a default message format:
	//   "[orkestra] {katalogName}/{crdKind} {crName}: {condition.Field} {op} {value}"
	Message string `yaml:"message,omitempty"`
}

type NotifyBlock struct {
	// Teams is the list of team names (from notification.teams) to alert.
	Teams []string `yaml:"teams"`
	// Message is a Go template expression for the notification body.
	// Overrides the team's own message template.
	// When empty, uses the team's configured message or the system default.
	Message string `yaml:"message,omitempty"`
}

type OperatorBoxConfig struct {
	// Default controls which reconciler implementation is used for this CRD.
	//
	// true  — GenericReconciler manages the full lifecycle automatically.
	//         Handles: finalizer add/remove, Kubernetes events, metrics, health state.
	//         HookFactory is optional — set for custom business logic.
	//         OnCreate/OnReconcile/OnDelete templates are only valid when Default: true.
	//
	// false — Custom reconciler. The user provides the full reconcile implementation.
	//         Constructor must be declared (in YAML mode) or set directly (Go mode).
	//         GenericReconciler is not used — the user owns the entire lifecycle.
	Default *bool `yaml:"default" json:"default,omitempty" validate:"omitempty"`

	// Finalizers — per-CRD finalizer list. Overrides the Katalog-level finalizer.
	// Applied by GenericReconciler when a CR is first created.
	// Stripped one-by-one before delete to unblock Kubernetes garbage collection.
	// If empty, falls back to the Katalog-level finalizer declaration.
	Finalizers []string `yaml:"finalizers" json:"finalizers,omitempty" validate:"omitempty"`

	// Hooks — declares a Go hook function for Default: true CRDs in typed or dynamic mode.
	// The function at Location.Function must match: func() domain.AnyReconcileHooks
	// Use this when you want full Go control over reconcile logic.
	// For declarative resource management without Go code, use OnCreate/OnReconcile/OnDelete.
	// Only one of Hooks or OnCreate/OnReconcile/OnDelete should be used — not both.
	Hooks *HookDeclaration `yaml:"hooks" json:"hooks,omitempty" validate:"omitempty"`

	// ConstructorDecl — declares a custom reconciler constructor for Default: false CRDs.
	// The function at Location.Function must match: NewReconcilerFunc
	// Required when Default: false in YAML mode.
	ConstructorDecl *ConstructorDeclaration `yaml:"constructor" json:"constructor,omitempty" validate:"omitempty"`

	// OnCreate — resources to create when the CR is first reconciled.
	OnCreate *HookTemplates `yaml:"onCreate" json:"onCreate,omitempty" validate:"omitempty"`

	// OnReconcile — drift correction resources applied on every reconcile.
	// Omit if onCreate alone is sufficient.
	OnReconcile *HookTemplates `yaml:"onReconcile" json:"onReconcile,omitempty" validate:"omitempty"`

	// OnDelete — cleanup resources applied before finalizer removal.
	// Omit for resources covered by owner reference cascade deletion.
	OnDelete *HookTemplates `yaml:"onDelete" json:"onDelete,omitempty" validate:"omitempty"`

	// HookFactory — called once at startCRDWorkers time to produce typed hooks.
	// nil → GenericReconciler runs with no user hooks.
	//       Finalizers, events, and metrics are still handled automatically.
	HookFactory func() domain.AnyReconcileHooks `yaml:"-" json:"-"`

	// Constructor — called once at startCRDWorkers time to build a custom reconciler.
	// Must not be nil when Default: false — enforced by Katalog validation at startup.
	Constructor NewReconcilerFunc `yaml:"-" json:"-"`

	// Status declares how Orkestra manages the CR's /status subresource.
	// nil (default): Layer 1 only — standard Ready condition after every reconcile.
	// non-nil: Layer 1 + Layer 2 declarative fields from Status.Fields.
	Status *StatusConfig `yaml:"status,omitempty" json:"status,omitempty"`

	// ProviderBlocks holds the parsed provider declarations from the Katalog.
	// Populated during Katalog loading via ParseProviderBlocks.
	// Not a YAML field — parsed from RawProviders after unmarshal.
	ProviderBlocks []ProviderBlock `yaml:"-" json:"-"`

	// RawProviders is the raw YAML map, populated during unmarshal.
	// Converted to ProviderBlocks in the Katalog loading step.
	RawProviders map[string][]map[string]interface{} `yaml:"providers,omitempty" json:"providers,omitempty"`

	// Cross declares cross-CRD observations.
	// Read before any resource groups — results available as .cross.<as>.status.*
	Cross []CrossCRDDeclaration `yaml:"cross,omitempty" json:"cross,omitempty"`

	// Autoscale declares runtime autoscale behavior for this operatorbox.
	// When declared, the autoscaler evaluates conditions on a ticker and applies
	// or restores worker/queue/resync overrides automatically.
	// nil → no autoscaling; CRD runs with its declared static worker count.
	Autoscale *AutoscaleSpec `yaml:"autoscale,omitempty" json:"autoscale,omitempty"`

	// Rollback declares failure-recovery behavior for this operatorbox.
	// When declared, Orkestra tracks consecutive reconcile failures and re-applies
	// the last known good spec when the trigger threshold is crossed.
	// nil → no rollback; failures are retried indefinitely.
	Rollback *RollbackBlock `yaml:"rollback,omitempty" json:"rollback,omitempty"`

	// When is an optional list of conditions that must all pass before
	// this field is written. If absent or empty, the field is always written.
	//
	// All conditions are AND-ed together.
	// To express OR logic, declare multiple StatusField entries for the same path.
	//
	// Conditions are evaluated against the full CR object map — the same
	// map available to template expressions. This means .status.phase,
	// .spec.image, .children.job.status.succeeded are all accessible.
	When []Condition `yaml:"when,omitempty"`

	AnyOf []Condition `yaml:"anyOf,omitempty"`
}

type PDBTemplateSource struct {
	Version string `yaml:"version" json:"version,omitempty"`

	// Name — PDB resource name. Default: "{{ .metadata.name }}-pdb"
	Name string `yaml:"name" json:"name,omitempty"`

	// Namespace — target namespace. Default: CR namespace.
	Namespace string `yaml:"namespace" json:"namespace,omitempty"`

	// Selector — label selector identifying the pods this PDB protects.
	// Keys are static; values support template expressions.
	Selector SelectorMap `yaml:"selector" json:"selector,omitempty"`

	// MinAvailable — minimum number of pods that must remain available.
	// Accepts integer strings ("1") or percentage strings ("50%").
	// Mutually exclusive with MaxUnavailable.
	MinAvailable string `yaml:"minAvailable" json:"minAvailable,omitempty"`

	// MaxUnavailable — maximum number of pods that may be unavailable.
	// Accepts integer strings ("1") or percentage strings ("25%").
	// Mutually exclusive with MinAvailable.
	MaxUnavailable string `yaml:"maxUnavailable" json:"maxUnavailable,omitempty"`

	// Labels applied to PDB metadata. Values support template expressions.
	Labels []ResourceLabel `yaml:"labels" json:"labels,omitempty"`

	Reconcile  bool         `yaml:"reconcile" json:"reconcile,omitempty"`
	Conditions []Condition  `yaml:"when,omitempty" json:"when,omitempty"`
	AnyOf      []Condition  `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`
	ForEach    *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`
}

type PVCTemplateSource struct {
	Version string `yaml:"version" json:"version,omitempty"`

	// Name — PVC name. Required.
	Name string `yaml:"name" json:"name,omitempty"`

	// Namespace — target namespace. Default: CR namespace.
	Namespace string `yaml:"namespace" json:"namespace,omitempty"`

	// StorageClassName — storage class to use. Empty means cluster default.
	StorageClassName string `yaml:"storageClassName" json:"storageClassName,omitempty"`

	// AccessModes — access modes. Default: ["ReadWriteOnce"].
	// Supports: ReadWriteOnce, ReadOnlyMany, ReadWriteMany, ReadWriteOncePod.
	AccessModes []string `yaml:"accessModes" json:"accessModes,omitempty"`

	// Storage — requested storage size (e.g. "10Gi"). Required.
	Storage string `yaml:"storage" json:"storage,omitempty" validate:"required"`

	// VolumeMode — Filesystem or Block. Default: Filesystem.
	VolumeMode string `yaml:"volumeMode" json:"volumeMode,omitempty"`

	// VolumeName — bind to a specific PV by name.
	VolumeName string `yaml:"volumeName" json:"volumeName,omitempty"`

	Labels []ResourceLabel `yaml:"labels" json:"labels,omitempty"`

	Reconcile  bool         `yaml:"reconcile" json:"reconcile,omitempty"`
	Conditions []Condition  `yaml:"when,omitempty" json:"when,omitempty"`
	AnyOf      []Condition  `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`
	ForEach    *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`
}

type PVTemplateSource struct {
	Version string `yaml:"version" json:"version,omitempty"`

	// Name — PV name. Required.
	Name string `yaml:"name" json:"name,omitempty"`

	// StorageClassName — storage class name.
	StorageClassName string `yaml:"storageClassName" json:"storageClassName,omitempty"`

	// Capacity — storage capacity (e.g. "10Gi"). Required.
	Capacity string `yaml:"capacity" json:"capacity,omitempty" validate:"required"`

	// AccessModes — access modes. Default: ["ReadWriteOnce"].
	AccessModes []string `yaml:"accessModes" json:"accessModes,omitempty"`

	// ReclaimPolicy — Retain, Delete, or Recycle. Default: Retain.
	ReclaimPolicy string `yaml:"reclaimPolicy" json:"reclaimPolicy,omitempty"`

	// HostPath — host path for HostPath volume type. Used for local/dev PVs.
	HostPath string `yaml:"hostPath" json:"hostPath,omitempty"`

	// CSI driver fields for cloud/CSI volumes.
	CSIDriver       string `yaml:"csiDriver" json:"csiDriver,omitempty"`
	CSIVolumeHandle string `yaml:"csiVolumeHandle" json:"csiVolumeHandle,omitempty"`

	Labels []ResourceLabel `yaml:"labels" json:"labels,omitempty"`

	Reconcile  bool         `yaml:"reconcile" json:"reconcile,omitempty"`
	Conditions []Condition  `yaml:"when,omitempty" json:"when,omitempty"`
	AnyOf      []Condition  `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`
	ForEach    *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`
}

type PlaceholderSource struct{}

type PodTemplateSource struct {
	// Version — OrkestraRegistry implementation version. Omit for latest.
	Version string `yaml:"version" json:"version,omitempty" validate:"omitempty"`

	// Name — Pod name.
	// Default when omitted: "{{ .metadata.name }}-pod"
	Name string `yaml:"name" json:"name,omitempty" validate:"omitempty"`

	// Image — container image. Required.
	// Static: "busybox:1.35" or Dynamic: "{{ .spec.image }}"
	Image string `yaml:"image" json:"image" validate:"omitempty"`

	// Port — container port as a string.
	// Static: "8080" or Dynamic: "{{ .spec.port }}"
	Port string `yaml:"port" json:"port,omitempty" validate:"omitempty"`

	// Namespace — target namespace.
	// Default when omitted: "{{ .metadata.namespace }}"
	Namespace string `yaml:"namespace" json:"namespace,omitempty" validate:"omitempty"`

	// Labels — applied to Pod metadata. Values support template expressions.
	Labels []ResourceLabel `yaml:"labels" json:"labels,omitempty" validate:"omitempty"`

	// Annotations — applied to Pod metadata. Values support template expressions.
	Annotations []ResourceLabel `yaml:"annotations" json:"annotations,omitempty" validate:"omitempty"`

	// Resources — static CPU and memory requests/limits.
	Resources *ResourceRequirements `yaml:"resources" json:"resources,omitempty" validate:"omitempty"`

	Conditions []Condition `yaml:"when,omitempty" json:"when,omitempty"`

	// ForEach declares dynamic expansion over a list field.
	// When set, one source declaration becomes N declarations — one per list element.
	// .item and .<as> are available in template expressions within this declaration.
	ForEach *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`

	// AnyOf holds OR conditions — at least one must pass for this resource to be created.
	// Works alongside the existing Conditions (when:) field which uses AND semantics.
	AnyOf []Condition `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`
}

type Provider interface {
	// Name returns the YAML block key this provider handles.
	// Must be unique across all registered providers.
	// Convention: lowercase, no hyphens (e.g. "aws", "database", "stripe").
	Name() string

	// Reconcile is called after all Kubernetes resources are reconciled.
	// It should bring external resources into alignment with the declared state.
	// Must be idempotent — called on every resync, not just on first creation.
	//
	// Return nil when:
	//   - External resource already matches desired state (no-op)
	//   - External resource was successfully created or updated
	//   - Resource is still provisioning (check again next cycle)
	//   - Declaration kind is unknown (log a warning, skip, return nil)
	//
	// Return non-nil error when:
	//   - External API is unreachable
	//   - Credentials are invalid or expired
	//   - A hard quota is exceeded
	//   - Any condition that will not resolve on the next retry without intervention
	Reconcile(ctx context.Context, req ReconcileRequest) error

	// Delete is called during finalizer execution before the CR is removed.
	// It should delete all external resources created for this CR.
	// Must be idempotent — if the resource does not exist, return nil.
	//
	// The finalizer is NOT removed until Delete returns nil.
	// Returning an error leaves the CR stuck in deletion — ensure
	// transient errors are retried and permanent errors are surfaced clearly.
	Delete(ctx context.Context, req DeleteRequest) error
}

type ProviderBlock struct {
	// Name is the provider block key — matches Provider.Name().
	Name string

	// Declarations is the ordered list of resource declarations in this block.
	// Each declaration specifies one external resource to manage.
	Declarations []RawProviderDeclaration
}

type ProviderDeclaration struct {
	// Kind is the first key in the YAML map entry: "rds", "s3", "product", "widget".
	Kind string

	// Fields are the resolved key-value pairs. Values are always strings —
	// template resolution produces strings; type conversion is the provider's
	// responsibility.
	Fields map[string]string
}

type ProviderRegistry interface {
	// Register adds a provider. Panics if a provider with the same name is
	// already registered — fail fast at startup rather than silently ignoring.
	Register(p Provider)

	// Get returns the provider for the given block name and true, or nil and
	// false if no provider is registered for that name.
	Get(name string) (Provider, bool)

	// Names returns all registered provider names.
	// Used by the validator to warn on unknown blocks in the Katalog.
	Names() []string

	// Len returns the number of registered providers.
	Len() int
}

type Queue struct {

	// Default: false — each CRD gets its own isolated workqueue.
	Default *bool `yaml:"default" json:"default,omitempty"`

	// MaxQueueDepth — maximum number of items in the per-CRD queue.
	// New items are rejected when the queue is full.
	// 0 → uses Orkestra-level default set by MAX_QUEUE_DEPTH env var.
	MaxQueueDepth int `yaml:"maxQueueDepth" json:"maxQueueDepth,omitempty" validate:"omitempty,gte=0"`

	// DegradeThreshold — number of consecutive reconcile failures before the
	// CRD health state transitions from healthy to degraded.
	// 0 → uses Orkestra-level default.
	DegradeThreshold int `yaml:"degradeThreshold" json:"degradeThreshold,omitempty" validate:"omitempty,gte=0"`
}

type RBACConfig struct {
	// Enabled controls whether RBAC is applied at startup.
	// Default: true when the rbac block is declared.
	Enabled *bool `yaml:"enabled,omitempty"`

	// CleanupOnShutdown controls whether RBAC is deleted on graceful shutdown.
	// Default: false — RBAC persists across restarts.
	CleanupOnShutdown bool `yaml:"cleanupOnShutdown,omitempty"`
}

type RawProviderDeclaration struct {
	// Kind is the resource type within the provider block.
	// Derived from the single key in the YAML map entry.
	// Examples: "s3", "rds", "route53", "database", "user", "collection"
	Kind string

	// Fields are the raw (unresolved) key-value pairs for this declaration.
	// Nested YAML maps are flattened with dot notation:
	//   credentials:
	//     secretName: my-secret
	// becomes Fields["credentials.secretName"] = "my-secret"
	//
	// Values may contain template expressions — resolved by the template
	// resolver before the provider is called.
	Fields map[string]string

	// Conditions are the when: conditions from this declaration (AND semantics).
	// Evaluated by Orkestra before calling the provider — declarations
	// whose conditions fail are removed from the list before dispatch.
	Conditions []Condition `yaml:"when,omitempty"`

	// AnyOf holds OR conditions — at least one must pass.
	AnyOf []Condition `yaml:"anyOf,omitempty"`
}

type ReconcileRequest struct {
	// Object is the full CR as an unstructured map.
	// Identical to the data available in Katalog template expressions.
	// Access patterns:
	//   spec:     obj["spec"].(map[string]interface{})["fieldName"]
	//   status:   obj["status"].(map[string]interface{})["phase"]
	//   children: obj["children"].(map[string]interface{})["deployment"]
	Object map[string]interface{}

	// Declarations are the pre-resolved provider block declarations.
	// Template expressions have already been evaluated against the CR.
	// Conditions have already been evaluated — only passing declarations arrive.
	// Each entry corresponds to one item in the YAML list.
	Declarations []ProviderDeclaration

	// Kube provides read-only access to cluster resources.
	// Use to read Secrets for credentials and ConfigMaps for configuration.
	Kube KubeReader

	// Logger is a structured logger pre-tagged with crd, resource, request_id.
	Logger zerolog.Logger

	// OwnerName is the CR's metadata.name.
	OwnerName string

	// OwnerNamespace is the CR's metadata.namespace.
	OwnerNamespace string
}

type RegistryRef struct {
	// Branch — track a branch (e.g. "main", "develop").
	// The latest commit on the branch is fetched.
	Branch string `yaml:"branch,omitempty"`

	// Version — pin to a release tag (e.g. "v1.2.0", "v2").
	// Git tags are fetched — version is used as the tag name.
	Version string `yaml:"version,omitempty"`

	// SHA — pin to an exact commit hash.
	// The full or partial SHA works (Git resolves partial SHAs).
	SHA string `yaml:"sha,omitempty"`
}

type RegistrySource struct {
	// URL — the registry URL.
	//
	// Git:  https://github.com/myorg/orkestra-registry
	// OCI:  ghcr.io/konduktor-io/orkestra-registry/postgres
	//
	// Shorthand — embed version with @:
	//   ghcr.io/konduktor-io/orkestra-registry/postgres@v14
	//   https://github.com/myorg/registry@main
	//
	// When @ is present, Version field is ignored.
	URL string `yaml:"url" validate:"required"`

	// Version — the version, tag, branch, or SHA to pull.
	//
	// For OCI:  semantic version tag    "v14", "v14.2.0"
	// For Git:  branch, tag, or SHA     "main", "v1.0.0", "abc123"
	//
	// Ignored when URL contains @.
	// Defaults to "main" for Git, "latest" for OCI when not set.
	Version string `yaml:"version,omitempty"`

	// OCI — when true, pull the pattern as an OCI artifact.
	// When false (default), pull via Git clone or raw file fetch.
	//
	// OCI artifacts are pulled using the ORAS protocol.
	// GitHub and GitLab URLs with oci: false use raw file HTTP — no clone needed.
	// Other Git URLs with oci: false use git clone.
	OCI bool `yaml:"oci,omitempty"`

	// UseKomposer — when true, load komposer.yaml from the pulled pattern.
	// When false (default), load katalog.yaml.
	//
	// Exactly one file is loaded — not both.
	//
	// UseKomposer: false (default)
	//   Use this when you want the CRD definitions and will override them
	//   inline in your own Komposer. This is the common case.
	//
	// UseKomposer: true
	//   Use this when you want to accept the upstream operator's full
	//   source tree as-is — their sources, their defaults, everything.
	//   Useful for internal teams with a canonical registry where the
	//   upstream Komposer is exactly what you want to run.
	//
	// Warning: loading a Komposer from a registry source means that
	// Komposer's own sources are also resolved. A Komposer that sources
	// other Katalogs will pull those too. Understand the upstream
	// dependency tree before enabling this.
	UseKomposer bool `yaml:"useKomposer,omitempty"`

	// Auth — optional authentication for the registry.
	// When empty, requests are unauthenticated.
	// Auth credentials are resolved from environment variables — never literals.
	Auth *FileSourceAuth `yaml:"auth,omitempty"`

	// Katalog — map of katalog names to their version references.
	// Key: katalog name (directory name under registry/katalogs/).
	// Value: version reference (branch, sha, or version tag).
	Katalog map[string]RegistryRef `yaml:"katalog,omitempty"`
}

type ReplicaSetTemplateSource struct {
	// Version — OrkestraRegistry implementation version to use. Omit for latest.
	Version string `yaml:"version" json:"version,omitempty" validate:"omitempty"`

	// Name — ReplicaSet and primary container name.
	// Supports template expressions.
	// Default when omitted: "{{ .metadata.name }}-replicaset"
	Name string `yaml:"name" json:"name,omitempty" validate:"omitempty"`

	// Image — container image. Required (must be declared here or resolvable from CR).
	// Static:  "nginx:1.25"
	// Dynamic: "{{ .spec.image }}"
	Image string `yaml:"image" json:"image" validate:"omitempty"`

	// Replicas — number of pod replicas as a string.
	// Static:  "3"
	// Dynamic: "{{ .spec.replicas }}"
	// Default: "1"
	Replicas string `yaml:"replicas" json:"replicas,omitempty" validate:"omitempty"`

	// Port — primary container port as a string.
	// Static:  "8080"
	// Dynamic: "{{ .spec.port }}"
	// Omit to expose no port.
	Port string `yaml:"port" json:"port,omitempty" validate:"omitempty"`

	// Namespace — target namespace for the ReplicaSet.
	// Default when omitted: "{{ .metadata.namespace }}" (same namespace as the CR).
	Namespace string `yaml:"namespace" json:"namespace,omitempty" validate:"omitempty"`

	// Labels — applied to the ReplicaSet ObjectMeta and the pod template.
	// Label values support template expressions.
	// Orkestra always adds: managed-by=orkestra, orkestra-owner=<cr-name>
	Labels []ResourceLabel `yaml:"labels" json:"labels,omitempty" validate:"omitempty"`

	// Annotations — applied to the ReplicaSet ObjectMeta only.
	// Annotation values support template expressions.
	Annotations []ResourceLabel `yaml:"annotations" json:"annotations,omitempty" validate:"omitempty"`

	// Resources — CPU and memory requests/limits for the primary container.
	// Values are static Kubernetes quantity strings.
	// Template expressions are not supported in resource quantities.
	Resources *ResourceRequirements `yaml:"resources" json:"resources,omitempty" validate:"omitempty"`

	// Env — environment variables for the primary container.
	// Keys are env var names. Values support template expressions.
	Env map[string]EnvVarSource `yaml:"env" json:"env,omitempty"`

	EnvFrom []EnvFromSource `yaml:"envFrom,omitempty" json:"envFrom,omitempty"`

	// Reconcile: true — also apply this declaration as drift correction on every
	// reconcile. Equivalent to declaring the same entry under both onCreate and
	// onReconcile. When false (default), only runs on onCreate (idempotent create).
	Reconcile bool `yaml:"reconcile" json:"reconcile,omitempty" validate:"omitempty"`

	// Conditions (when) — AND semantics.
	Conditions []Condition `yaml:"when,omitempty" json:"when,omitempty"`

	// ForEach declares dynamic expansion over a list field.
	ForEach *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`

	// AnyOf holds OR conditions — at least one must pass for this resource.
	AnyOf []Condition `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`

	// WorkingDirectory sets the container's working directory (container.WorkingDir).
	WorkingDirectory string `yaml:"workingDirectory,omitempty" json:"workingDirectory,omitempty"`
}

type ResourceCheck struct {
	Get func(crd CRDEntry) bool
}

type ResourceLabel struct {
	Key   string `yaml:"key" json:"key" validate:"required"`
	Value string `yaml:"value" json:"value" validate:"required"`
}

type ResourceRequirements struct {
	Requests map[string]string `yaml:"requests" json:"requests,omitempty" validate:"omitempty"`
	Limits   map[string]string `yaml:"limits" json:"limits,omitempty" validate:"omitempty"`
}

type ResourceSelector []ResourceLabel

type RestrictedNamespaces []string

type RollbackBlock struct {
	// Trigger declares when rollback activates.
	// Both fields are optional — set one or both.
	// When both are set: triggers when ConsecutiveFailures failures
	// occur AND those failures all happened within WithinDuration.
	Trigger RollbackTrigger `yaml:"trigger"`

	// OnRollback declares the resource groups to apply when rollback is active.
	// Uses the same grammar as OnReconcile — deployments, services, configMaps, etc.
	// Templates may reference .previous.spec.*, .previous.metadata.*, etc.
	// which are hydrated from the previous-spec annotation.
	OnRollback *HookTemplates `yaml:"onRollback,omitempty"`
}

type RollbackPhase string

type RollbackTrigger struct {
	// ConsecutiveFailures is the number of consecutive reconcile failures
	// that triggers rollback. Default: 3.
	ConsecutiveFailures int `yaml:"consecutiveFailures,omitempty"`

	// WithinDuration is the time window within which ConsecutiveFailures
	// must occur for rollback to trigger.
	// When omitted: any ConsecutiveFailures consecutive failures trigger rollback,
	// regardless of how long ago the first failure occurred.
	// When set: only triggers if all failures occurred within this window.
	// Example: 3 failures within 5m = trigger; 3 failures over 2 hours = no trigger.
	WithinDuration *Duration `yaml:"withinDuration,omitempty"`
}

type ScaleTargetRef struct {
	APIVersion string `yaml:"apiVersion" json:"apiVersion"`
	Kind       string `yaml:"kind" json:"kind"`
	Name       string `yaml:"name" json:"name"`
}

type SecretKeyRef struct {
	Name string `yaml:"name" json:"name"`
	Key  string `yaml:"key" json:"key"`
}

type SecretTemplateSource struct {
	// Version — OrkestraRegistry implementation version. Omit for latest.
	Version string `yaml:"version" json:"version,omitempty" validate:"omitempty"`

	// Name — Secret name.
	// Default when omitted: "{{ .metadata.name }}-secret"
	Name string `yaml:"name" json:"name,omitempty" validate:"omitempty"`

	// Namespace — target namespace.
	// Default when omitted: "{{ .metadata.namespace }}"
	Namespace string `yaml:"namespace" json:"namespace,omitempty" validate:"omitempty"`

	// Type — Kubernetes Secret type.
	// Default: "Opaque"
	Type string `yaml:"type" json:"type,omitempty" validate:"omitempty"`

	// Data — static key-value entries.
	// Values are plain strings — template expressions are not supported here.
	// If you need templated or dynamic values, use a custom Go hook.
	Data map[string]string `yaml:"data" json:"data,omitempty" validate:"omitempty"`

	// Labels — applied to Secret metadata. Values support template expressions.
	Labels []ResourceLabel `yaml:"labels" json:"labels,omitempty" validate:"omitempty"`

	// Annotations — applied to Secret metadata.
	Annotations map[string]string `yaml:"annotations,omitempty" json:"annotations,omitempty"`

	// FromSecret — name of an existing Secret to copy data from.
	// Orkestra reads this at reconcile time — copies stay in sync with the source.
	FromSecret string `yaml:"fromSecret" json:"fromSecret,omitempty" validate:"omitempty"`

	// FromNamespace — namespace where FromSecret lives.
	// Default: same namespace as the CR.
	FromNamespace string `yaml:"fromNamespace" json:"fromNamespace,omitempty" validate:"omitempty"`

	// ToNamespaces - a list of target namespaces
	// Default when omitted: "{{ .metadata.namespace }}"
	ToNamespaces []string `yaml:"toNamespaces" json:"toNamespaces,omitempty" validate:"omitempty"`

	// Reconcile: true — also apply this declaration as drift correction on every
	// reconcile. Equivalent to declaring the same entry under both onCreate and
	// onReconcile. When false (default), only runs on onCreate (idempotent create).
	Reconcile bool `yaml:"reconcile" json:"reconcile,omitempty" validate:"omitempty"`

	Conditions []Condition `yaml:"when,omitempty" json:"when,omitempty"`

	// Once controls idempotent secret generation.
	// true  — evaluate templates and create only when the Secret does not exist.
	//         Use with random notes (randomAlphanumeric, randomHex, randomBase64).
	// false — standard create/update behavior (default).
	Once bool `yaml:"once,omitempty" json:"once,omitempty"`

	// ForEach declares dynamic expansion (same as other resource types)
	ForEach *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`

	// AnyOf holds OR conditions (same as other resource types)
	AnyOf []Condition `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`

	// RotateAfter declares a time-based rotation threshold.
	// When set alongside once: true, the Secret is recreated when its age
	// exceeds this duration. The creation time is tracked via the annotation:
	//   orkestra.konductor.io/generated-at: "2026-04-06T08:00:00Z"
	//
	// Supported formats: 30s, 5m, 12h, 90d, 1y
	// Days (d) and years (y) are extensions beyond Go's standard duration format.
	//
	// Example:
	//   secrets:
	//     - name: "{{ .metadata.name }}-credentials"
	//       once: true
	//       rotateAfter: 90d
	//       data:
	//         password: "{{ randomAlphanumeric 32 }}"
	RotateAfter string `yaml:"rotateAfter,omitempty" json:"rotateAfter,omitempty"`

	// TLS declares self-signed CA and server certificate generation.
	// When set, the data: block is ignored — the Secret is created as type
	// kubernetes.io/tls with fields: tls.crt, tls.key, ca.crt
	//
	// Default Secret name when name is empty: "orkestra-tls"
	// Default validFor when empty: same as rotateAfter, or "1y"
	//
	// Example:
	//   secrets:
	//     - name: "{{ .metadata.name }}-tls"
	//       once: true
	//       rotateAfter: 1y
	//       tls:
	//         commonName: "{{ .metadata.name }}.{{ .metadata.namespace }}.svc"
	//         dnsNames:
	//           - "{{ .metadata.name }}"
	//           - "{{ .metadata.name }}.{{ .metadata.namespace }}"
	//           - "{{ .metadata.name }}.{{ .metadata.namespace }}.svc"
	//           - "{{ .metadata.name }}.{{ .metadata.namespace }}.svc.cluster.local"
	//         validFor: 1y
	TLS *TLSSpec `yaml:"tls,omitempty" json:"tls,omitempty"`
}

type SelectorMap map[string]string

type ServiceAccountTemplateSource struct {
	// Version — OrkestraRegistry implementation version. Omit for latest.
	Version string `yaml:"version" json:"version,omitempty" validate:"omitempty"`

	// Name — ServiceAccount name.
	// Default when omitted: "{{ .metadata.name }}-sa"
	Name string `yaml:"name" json:"name,omitempty" validate:"omitempty"`

	// Namespace — target namespace.
	// Default when omitted: "{{ .metadata.namespace }}"
	Namespace string `yaml:"namespace" json:"namespace,omitempty" validate:"omitempty"`

	// Labels — applied to ServiceAccount metadata. Values support template expressions.
	Labels []ResourceLabel `yaml:"labels" json:"labels,omitempty" validate:"omitempty"`

	Conditions []Condition `yaml:"when,omitempty" json:"when,omitempty"`

	// Reconcile: true — also apply this declaration as drift correction on every
	// reconcile. Equivalent to declaring the same entry under both onCreate and
	// onReconcile. When false (default), only runs on onCreate (idempotent create).
	Reconcile bool `yaml:"reconcile" json:"reconcile,omitempty" validate:"omitempty"`

	// ForEach declares dynamic expansion over a list field.
	// When set, one source declaration becomes N declarations — one per list element.
	// .item and .<as> are available in template expressions within this declaration.
	ForEach *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`

	// AnyOf holds OR conditions — at least one must pass for this resource to be created.
	// Works alongside the existing Conditions (when:) field which uses AND semantics.
	AnyOf []Condition `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`
}

type ServiceTemplateSource struct {
	// Version — OrkestraRegistry implementation version. Omit for latest.
	Version string `yaml:"version" json:"version,omitempty" validate:"omitempty"`

	// Name — Service name.
	// Default when omitted: "{{ .metadata.name }}-svc"
	Name string `yaml:"name" json:"name,omitempty" validate:"omitempty"`

	// Type — Kubernetes Service type.
	// Accepted values: ClusterIP, NodePort, LoadBalancer.
	// Default: ClusterIP.
	Type string `yaml:"type" json:"type,omitempty" validate:"omitempty"`

	// Port — Service port as a string.
	// Static: "80" or Dynamic: "{{ .spec.servicePort }}"
	Port string `yaml:"port" json:"port" validate:"omitempty"`

	// TargetPort — container port the Service routes traffic to.
	// Static: "8080" or Dynamic: "{{ .spec.containerPort }}"
	TargetPort string `yaml:"targetPort" json:"targetPort,omitempty" validate:"omitempty"`

	// Namespace — target namespace.
	// Default when omitted: "{{ .metadata.namespace }}"
	Namespace string `yaml:"namespace" json:"namespace,omitempty" validate:"omitempty"`

	// Labels — applied to Service metadata. Values support template expressions.
	Labels []ResourceLabel `yaml:"labels" json:"labels,omitempty" validate:"omitempty"`

	// Selector filters which pods this service will route traffic to
	// Useful in forEach situations where the labels would likely be the same
	Selector SelectorMap `yaml:"selector" json:"selector,omitempty" validate:"omitempty"`

	// Reconcile: true — also apply this declaration as drift correction on every
	// reconcile. Equivalent to declaring the same entry under both onCreate and
	// onReconcile. When false (default), only runs on onCreate (idempotent create).
	Reconcile bool `yaml:"reconcile" json:"reconcile,omitempty" validate:"omitempty"`

	Conditions []Condition `yaml:"when,omitempty" json:"when,omitempty"`

	// ForEach declares dynamic expansion over a list field.
	// When set, one source declaration becomes N declarations — one per list element.
	// .item and .<as> are available in template expressions within this declaration.
	ForEach *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`

	// AnyOf holds OR conditions — at least one must pass for this resource to be created.
	// Works alongside the existing Conditions (when:) field which uses AND semantics.
	AnyOf []Condition `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`
}

type StatefulSetTemplateSource struct {
	Version string `yaml:"version" json:"version,omitempty"`

	// Name — StatefulSet name. Default: "{{ .metadata.name }}".
	Name string `yaml:"name" json:"name,omitempty"`

	// Namespace — target namespace. Default: CR namespace.
	Namespace string `yaml:"namespace" json:"namespace,omitempty"`

	// Image — container image. Required.
	Image string `yaml:"image" json:"image,omitempty" validate:"required"`

	// Tag — image tag. Default: "latest".
	Tag string `yaml:"tag" json:"tag,omitempty"`

	// Replicas — number of pod replicas. Default: "1".
	Replicas string `yaml:"replicas" json:"replicas,omitempty"`

	// Port — container port. "0" or empty means no port exposed.
	Port string `yaml:"port" json:"port,omitempty"`

	// ServiceName — name of the headless Service governing the StatefulSet.
	// Default: same as Name.
	ServiceName string `yaml:"serviceName" json:"serviceName,omitempty"`

	// StorageClass — storage class for auto-generated VolumeClaimTemplates.
	StorageClass string `yaml:"storageClass" json:"storageClass,omitempty"`

	// StorageSize — size of each volume claim (e.g. "10Gi"). Required when StorageClass is set.
	StorageSize string `yaml:"storageSize" json:"storageSize,omitempty"`

	// MountPath — mount path for the storage volume inside the container. Default: "/data".
	MountPath string `yaml:"mountPath" json:"mountPath,omitempty"`

	Labels      []ResourceLabel         `yaml:"labels" json:"labels,omitempty"`
	Annotations []ResourceLabel         `yaml:"annotations" json:"annotations,omitempty"`
	Env         map[string]EnvVarSource `yaml:"env" json:"env,omitempty"`
	EnvFrom     []EnvFromSource         `yaml:"envFrom,omitempty" json:"envFrom,omitempty"`
	Resources   *ResourceRequirements   `yaml:"resources" json:"resources,omitempty"`

	Reconcile  bool         `yaml:"reconcile" json:"reconcile,omitempty"`
	Conditions []Condition  `yaml:"when,omitempty" json:"when,omitempty"`
	AnyOf      []Condition  `yaml:"anyOf,omitempty" json:"anyOf,omitempty"`
	ForEach    *ForEachSpec `yaml:"forEach,omitempty" json:"forEach,omitempty"`
}

type StatusConfig struct {
	// Fields — list of status fields to write after every successful reconcile.
	// Resolved in declaration order. Later fields win on path conflict.
	Fields []StatusFieldSpec `yaml:"fields,omitempty" json:"fields,omitempty"`

	// Conditions — whether to write the standard Ready condition automatically.
	// Default: true. Set to false to opt out of automatic condition management.
	// When true, Orkestra writes:
	//   status.conditions[type=Ready]:
	//     status: "True" | "False"
	//     reason: ReconcileSucceeded | ReconcileError
	//     message: "" | "<error message>"
	//     lastTransitionTime: <now>
	//   status.observedGeneration: <metadata.generation>
	//
	// Setting false is rarely needed. Do it only when your CRD's status
	// schema explicitly forbids a conditions field, or when you manage
	// conditions entirely via Go hooks.
	Conditions *bool `yaml:"conditions,omitempty" json:"conditions,omitempty"`
}

type StatusFieldSpec struct {
	// Path — dot-notation path relative to status.
	// "phase"            → status.phase
	// "database.host"    → status.database.host
	// "ready"            → status.ready
	Path string `yaml:"path" json:"path" validate:"required"`

	// Value — the value to write. Supports template expressions.
	// Resolved against the full CR object map at reconcile time.
	// Empty string is written as-is — declare a static empty string to clear a field.
	Value string `yaml:"value" json:"value"`

	// Type — optional explicit type for the resolved value.
	// If omitted, the value is written as a string.
	//
	// Supported values:
	//   "string", "str, "" (default)
	//   "int", "integer"
	//   "float"
	//   "bool", "boolean"
	//   "auto" — infer type from the resolved value
	Type string `yaml:"type,omitempty" json:"type,omitempty"`

	// When is an optional list of conditions that must all pass before
	// this field is written. If absent or empty, the field is always written.
	//
	// All conditions are AND-ed together.
	// To express OR logic, declare multiple StatusField entries for the same path.
	//
	// Conditions are evaluated against the full CR object map — the same
	// map available to template expressions. This means .status.phase,
	// .spec.image, .children.job.status.succeeded are all accessible.
	When []Condition `yaml:"when,omitempty"`

	// AnyOf — optional OR-conditions. If any condition passes, the field is written.
	// Useful for multi-branch declarative state machines.
	AnyOf []Condition `yaml:"anyOf,omitempty"`
}

type TLSSpec struct {
	// CommonName is the certificate's CN field.
	//   commonName: "{{ .metadata.name }}.{{ .metadata.namespace }}.svc"
	CommonName string `yaml:"commonName"`

	// DNSNames are the Subject Alternative Names.
	// Template expressions supported per entry.
	DNSNames []string `yaml:"dnsNames,omitempty"`

	// ValidFor is the certificate validity period.
	// Default: same as rotateAfter, or 1y if rotateAfter is not set.
	// Must be >= rotateAfter to avoid immediate expiry on rotation.
	ValidFor string `yaml:"validFor,omitempty"`

	// Organization is the cert's O field. Default: "orkestra"
	Organization string `yaml:"organization,omitempty"`
}

type TimeWindow struct {
	// After — active after this time (format: "HH:MM" in 24h).
	After string `yaml:"after,omitempty"`

	// Before — active before this time (format: "HH:MM" in 24h).
	Before string `yaml:"before,omitempty"`
}

type ValidationAction string

type ValidationConfig struct {
	// Rules — evaluated in declaration order.
	// All rules are evaluated before returning — all violations are reported
	// together so the user can fix everything in one cycle.
	Rules []ValidationRule `yaml:"rules,omitempty" json:"rules,omitempty"`
}

type ValidationRule struct {
	// Field — dot-notation path to the CR field being validated.
	// e.g. "spec.image", "metadata.labels.tier", "spec.db.engine"
	Field string `yaml:"field" json:"field" validate:"required"`

	// Message — shown in the Kubernetes event, webhook response, and operator
	// log when this rule is violated. Make it actionable.
	Message string `yaml:"message" json:"message" validate:"required"`

	// Action — what happens when this rule fails.
	// deny (default): block at admission, halt at reconcile.
	// warn: warning at admission, advisory at reconcile.
	Action ValidationAction `yaml:"action,omitempty" json:"action,omitempty"`

	// Shorthands — use these for the common cases.
	Equals      string `yaml:"equals,omitempty" json:"equals,omitempty"`
	NotEquals   string `yaml:"notEquals,omitempty" json:"notEquals,omitempty"`
	Prefix      string `yaml:"prefix,omitempty" json:"prefix,omitempty"`
	Suffix      string `yaml:"suffix,omitempty" json:"suffix,omitempty"`
	Contains    string `yaml:"contains,omitempty" json:"contains,omitempty"`
	Min         string `yaml:"min,omitempty" json:"min,omitempty"` // numeric, inclusive
	Max         string `yaml:"max,omitempty" json:"max,omitempty"` // numeric, inclusive
	GreaterThan string `yaml:"greaterThan,omitempty" json:"greaterThan,omitempty"`
	LessThan    string `yaml:"lessThan,omitempty" json:"lessThan,omitempty"`

	// Explicit operator form — use when no shorthand covers the comparison.
	Operator  ConditionOperator `yaml:"operator,omitempty" json:"operator,omitempty"`
	Value     string            `yaml:"value,omitempty" json:"value,omitempty"`
	ValueType string            `yaml:"valueType,omitempty"` // "string", "int", "bool"
}

type WebhooksConfig struct {
	// Admission controls the ValidatingWebhookConfiguration and MutatingWebhookConfiguration.
	Admission *AdmissionWebhookToggle `yaml:"admission,omitempty"`

	// FailurePolicy controls what the API server does when Orkestra is unreachable
	// for admission calls. "Fail" or "Ignore".
	// Default: WEBHOOKS_FAILURE_POLICY env / "Ignore".
	FailurePolicy string `yaml:"failurePolicy,omitempty"`

	// ServiceName is the Kubernetes Service fronting Orkestra's HTTPS server.
	// Shared with deletion protection when both are enabled.
	// Default: ORKESTRA_SERVICE_NAME env / "orkestra".
	ServiceName string `yaml:"serviceName,omitempty"`

	// CleanupOnShutdown controls whether Admission webhook is deleted on graceful shutdown.
	// Default: false — Admission webhook persists across restarts.
	CleanupOnShutdown bool `yaml:"cleanupOnShutdown,omitempty"`
}