v1

type AccessEndpoint struct {
	// Name is a unique identifier for this endpoint within the class.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
	Name string `json:"name"`
	// Protocol is the wire protocol for this endpoint.
	Protocol RouteProtocol `json:"protocol"`
	// Port is the Service port of the endpoint's Service — the routable
	// truth for the routing provider's mirror Service and route backends.
	// Usually identical to the container port; where they differ, the
	// Service port wins.
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	Port int32 `json:"port"`
	// ServiceName overrides the conventional `<release-name>-<endpoint-name>`
	// name of the endpoint's child-cluster Service. For charts whose Service
	// names don't derive from the release name (fullnameOverride, third-party
	// umbrella subcharts like jupyterhub's `proxy-public`). Unambiguous even
	// for fixed names because each workspace runs in its own namespace.
	// Same convention-plus-override pattern as resourceInjection.
	// +optional
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
	ServiceName string `json:"serviceName,omitempty"`
	// Description is a human-readable summary shown to users.
	// +optional
	Description string `json:"description,omitempty"`
}

type AccessEntry struct {
	// Name is the access endpoint name from the WorkspaceClass.
	Name string `json:"name"`
	// Protocol is the endpoint's wire protocol.
	Protocol RouteProtocol `json:"protocol"`
	// URL is where the endpoint is reachable, e.g.
	// https://thorsten-nb.dos-lab.ex.ls or ssh://dos-lab.ex.ls:2207.
	// Empty while the route is not yet resolvable.
	// +optional
	URL string `json:"url,omitempty"`
	// Ready reports whether the platform side of routing is programmed.
	// Application-level health remains the chart's readiness probes.
	Ready bool `json:"ready"`
	// Message explains why an entry is not ready (e.g. port pool exhausted).
	// +optional
	Message string `json:"message,omitempty"`
}

type ClusterDeploymentRef struct {
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name"`
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	Namespace string `json:"namespace"`
}

type ConfigFieldType string

type EventSummary struct {
	// LastSeen is when the event last occurred.
	// +optional
	LastSeen metav1.Time `json:"lastSeen,omitempty"`
	// Type is Normal or Warning.
	// +optional
	Type   string `json:"type,omitempty"`
	Reason string `json:"reason"`
	// +optional
	Message string `json:"message,omitempty"`
}

type FailureContext struct {
	// PhaseWhenFailed is the phase the workspace was in when it failed
	// (e.g. Deploying, InstallingPrerequisites).
	// +optional
	PhaseWhenFailed WorkspaceDeploymentPhase `json:"phaseWhenFailed,omitempty"`
	// Reason is the machine-readable failure reason, mirroring the failing
	// condition's reason (e.g. HelmReleaseFailed, PrerequisitesNotReady,
	// RoutingInfraNotReady).
	// +optional
	Reason string `json:"reason,omitempty"`
	// ServiceSetStatus snapshots the workspace ServiceSet's reported
	// service states at failure time.
	// +optional
	ServiceSetStatus *ServiceSetStatusSummary `json:"serviceSetStatus,omitempty"`
	// RecentEvents lists the most recent Kubernetes events recorded for
	// this WorkspaceDeployment, newest first.
	// +optional
	RecentEvents []EventSummary `json:"recentEvents,omitempty"`
}

type FeasibilityStatus struct {
	// Fits is true when the demanded resources can be satisfied.
	Fits bool `json:"fits"`
	// EvaluatedAt is when this feasibility verdict was computed.
	EvaluatedAt metav1.Time `json:"evaluatedAt"`
	// Demanded is the total resource demand that was checked
	// (Replicas × PerReplica from the merged class+deployment spec).
	Demanded ResourceTotals `json:"demanded"`
	// Available is the cluster-wide free capacity at evaluation time.
	Available ResourceTotals `json:"available"`
	// Missing describes what's lacking when Fits=false. Nil when Fits=true.
	// +optional
	Missing *ResourceTotals `json:"missing,omitempty"`
	// Message is a human-readable summary.
	// +optional
	Message string `json:"message,omitempty"`
}

type GPUVendor string

type InjectionPath string

type PrerequisitePhase string

type PrerequisiteSource string

type PrerequisiteSpec struct {
	// ServiceTemplate references the prerequisite ServiceTemplate.
	ServiceTemplate ServiceTemplateRef `json:"serviceTemplate"`
	// Namespace is the target namespace on the child cluster for this shared
	// prerequisite install. A prerequisite is a per-cluster singleton, so this
	// namespace is a cluster-global property even though it is authored per
	// class. When unset, the install lands in "default" and the class accepts
	// whatever namespace another provider (a colony service or another class's
	// install) already placed the prerequisite in; when set explicitly, the
	// namespace must match wherever the singleton actually lives or the
	// WorkspaceDeployment fails with a namespace conflict (ADR-0007).
	// +optional
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
	// +kubebuilder:validation:MaxLength=63
	Namespace string `json:"namespace,omitempty"`
	// Values are optional Helm value overrides applied when installing this
	// prerequisite. When nil, chart defaults are used.
	// +optional
	Values *apiextensionsv1.JSON `json:"values,omitempty"`
}

type PrerequisiteStatus struct {
	// Name is the ServiceTemplate name from WorkspaceClass.spec.prerequisites.
	Name string `json:"name"`
	// Phase is the current state of this prerequisite.
	Phase PrerequisitePhase `json:"phase"`
	// Source identifies who is providing the prerequisite.
	// +optional
	Source PrerequisiteSource `json:"source,omitempty"`
	// Namespace is where the shared prerequisite install actually resides on
	// the child cluster: the incumbent's namespace when one exists, otherwise
	// the namespace this class would install into.
	// +optional
	Namespace string `json:"namespace,omitempty"`
	// Message is a human-readable detail (e.g., the underlying failure reason).
	// +optional
	Message string `json:"message,omitempty"`
}

type ResourceInjectionMap struct {
	// Replicas lists Helm value paths receiving the resolved replica count (int).
	// +optional
	// +listType=set
	Replicas []InjectionPath `json:"replicas,omitempty"`
	// CPU lists Helm value paths receiving the resolved per-replica CPU (string).
	// +optional
	// +listType=set
	CPU []InjectionPath `json:"cpu,omitempty"`
	// Memory lists Helm value paths receiving the resolved per-replica memory (string).
	// +optional
	// +listType=set
	Memory []InjectionPath `json:"memory,omitempty"`
	// Storage lists Helm value paths receiving the resolved per-replica storage (string).
	// +optional
	// +listType=set
	Storage []InjectionPath `json:"storage,omitempty"`
	// GPUCount lists Helm value paths receiving the resolved per-replica GPU count (int).
	// +optional
	// +listType=set
	GPUCount []InjectionPath `json:"gpuCount,omitempty"`
	// GPUVendor lists Helm value paths receiving the resolved GPU vendor (string).
	// +optional
	// +listType=set
	GPUVendor []InjectionPath `json:"gpuVendor,omitempty"`
	// GPUType lists Helm value paths receiving the resolved GPU type (string).
	// +optional
	// +listType=set
	GPUType []InjectionPath `json:"gpuType,omitempty"`
}

type ResourceRequirements struct {
	// CPU is the number of CPU cores requested (e.g. "4", "500m").
	// +optional
	CPU *resource.Quantity `json:"cpu,omitempty"`
	// Memory is the amount of memory requested (e.g. "16Gi").
	// +optional
	Memory *resource.Quantity `json:"memory,omitempty"`
	// Storage is the amount of persistent storage requested (e.g. "100Gi").
	// +optional
	Storage *resource.Quantity `json:"storage,omitempty"`
	// GPUCount is the number of GPUs requested per replica.
	// +optional
	// +kubebuilder:validation:Minimum=0
	GPUCount *int32 `json:"gpuCount,omitempty"`
	// GPUVendor constrains the GPU vendor (NVIDIA or AMD). Set on a
	// WorkspaceClass to express chart-level vendor compatibility (e.g. CUDA
	// vs ROCm); inheritable into a WorkspaceDeployment that doesn't override it.
	// +optional
	GPUVendor *GPUVendor `json:"gpuVendor,omitempty"`
	// GPUType is a deployment-time preference for a specific GPU model
	// (e.g. "H100", "A100", "L40"). When unset on a WorkspaceDeployment,
	// feasibility matches GPUs of any model. Cannot be set on a
	// WorkspaceClass — type is a per-deployment cluster-dependent choice.
	// +optional
	GPUType *string `json:"gpuType,omitempty"`
	// GPUNodeSelector is a raw, exact-match node-label selector for targeting a
	// GPU directly (e.g. a GFD/AMD label like {"nvidia.com/gpu.product":
	// "NVIDIA-H100-80GB-HBM3"}). It is the power-user/exact escape hatch
	// alongside gpuType: both compile to one GPU Selector that the operator
	// gate validates and the chart applies, so a request that passes the gate
	// is always placeable (ADR-0002). Usable even on clusters that lack the
	// canonical exalsius.ai/gpu-model label. Like gpuType, it is a
	// per-deployment cluster-dependent choice and cannot be set on a class.
	// +optional
	GPUNodeSelector map[string]string `json:"gpuNodeSelector,omitempty"`
}

type ResourceTotals struct {
	// CPU in cores (decimal-encoded resource.Quantity).
	// +optional
	CPU *resource.Quantity `json:"cpu,omitempty"`
	// Memory in bytes.
	// +optional
	Memory *resource.Quantity `json:"memory,omitempty"`
	// Storage in bytes.
	// +optional
	Storage *resource.Quantity `json:"storage,omitempty"`
	// GPUCount is the total number of GPUs.
	// +optional
	GPUCount *int32 `json:"gpuCount,omitempty"`
	// GPUVendor identifies the vendor that was matched (when feasibility
	// considered vendor as a constraint). Empty when wildcard.
	// +optional
	GPUVendor *GPUVendor `json:"gpuVendor,omitempty"`
	// GPUType identifies the GPU model that was matched. Empty when wildcard.
	// +optional
	GPUType *string `json:"gpuType,omitempty"`
}

type RouteProtocol string

type ServiceSetStatusSummary struct {
	// Name of the ServiceSet.
	Name string `json:"name"`
	// Deployed mirrors ServiceSet.status.deployed.
	// +optional
	Deployed bool `json:"deployed,omitempty"`
	// Services lists the per-service states.
	// +optional
	Services []ServiceStateSummary `json:"services,omitempty"`
}

type ServiceStateSummary struct {
	Name string `json:"name"`
	// State is the k0rdent service state (e.g. Deployed, Failed).
	// +optional
	State string `json:"state,omitempty"`
	// FailureMessage carries the underlying failure detail (e.g. the Helm
	// error).
	// +optional
	FailureMessage string `json:"failureMessage,omitempty"`
}

type ServiceTemplateRef struct {
	// Name is the name of the ServiceTemplate CR.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name"`
	// Namespace of the ServiceTemplate. When unspecified, the system namespace is implied.
	// +optional
	Namespace string `json:"namespace,omitempty"`
	// VersionConstraint is an optional SemVer constraint (e.g. ">=1.2.0").
	// +optional
	VersionConstraint string `json:"versionConstraint,omitempty"`
}

type UserFacingConfigField struct {
	// HelmValuePath is a dot-delimited path into values.yaml (e.g. "jupyter.password").
	// +kubebuilder:validation:MinLength=1
	HelmValuePath string `json:"helmValuePath"`
	// DisplayName is the label shown to the user in the CLI prompt.
	// +kubebuilder:validation:MinLength=1
	DisplayName string `json:"displayName"`
	// Description provides additional context shown as help text.
	// +optional
	Description string `json:"description,omitempty"`
	// Type is the input type for validation and display.
	// +kubebuilder:default=string
	Type ConfigFieldType `json:"type,omitempty"`
	// Required indicates the user must provide a value.
	// +optional
	Required bool `json:"required,omitempty"`
	// Default is the default value shown in the prompt.
	// +optional
	Default *apiextensionsv1.JSON `json:"default,omitempty"`
	// Options constrains the input to a closed set of allowed values.
	// +optional
	Options []string `json:"options,omitempty"`
}

type WorkspaceClass struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   WorkspaceClassSpec   `json:"spec"`
	Status WorkspaceClassStatus `json:"status,omitempty"`
}

type WorkspaceClassList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []WorkspaceClass `json:"items"`
}

type WorkspaceClassSpec struct {
	// DisplayName is the human-readable name shown in the workspace catalog.
	// +kubebuilder:validation:MinLength=1
	DisplayName string `json:"displayName"`
	// Description provides a user-facing summary of what this workspace type offers.
	// +optional
	Description string `json:"description,omitempty"`

	// ServiceTemplate references the k0rdent ServiceTemplate CR that wraps the
	// Helm chart for this workspace type.
	ServiceTemplate ServiceTemplateRef `json:"serviceTemplate"`

	// DefaultResources are applied when a WorkspaceDeployment does not override them.
	DefaultResources WorkspaceResourceSpec `json:"defaultResources"`

	// Prerequisites lists additional ServiceTemplates that must be healthy on the
	// target cluster before the workspace can be deployed.
	// +optional
	Prerequisites []PrerequisiteSpec `json:"prerequisites,omitempty"`

	// AccessEndpoints declares the network endpoints this workspace type exposes.
	// +optional
	// +listType=map
	// +listMapKey=name
	AccessEndpoints []AccessEndpoint `json:"accessEndpoints,omitempty"`

	// UserFacingConfig lists Helm value paths that the CLI should prompt for.
	// +optional
	// +listType=map
	// +listMapKey=helmValuePath
	UserFacingConfig []UserFacingConfigField `json:"userFacingConfig,omitempty"`

	// DeployTimeout is the maximum time to wait for the workspace Helm release
	// to become ready. Useful for workspaces with large images that take long to pull.
	// Defaults to 15 minutes if not set.
	// +optional
	DeployTimeout *metav1.Duration `json:"deployTimeout,omitempty"`

	// PrerequisiteDeployTimeout overrides DeployTimeout for prerequisite Helm
	// releases. Useful when prerequisite operators take noticeably longer or
	// shorter to install than the workspace itself. Defaults to DeployTimeout
	// when nil.
	// +optional
	PrerequisiteDeployTimeout *metav1.Duration `json:"prerequisiteDeployTimeout,omitempty"`

	// DefaultValues provides base Helm values that are always applied.
	// +optional
	DefaultValues *apiextensionsv1.JSON `json:"defaultValues,omitempty"`

	// ResourceInjection optionally maps resolved per-replica resource fields
	// to additional Helm value paths in spec.values. The standard
	// `_exalsius.resources` path is always populated automatically — this
	// field adds chart-specific paths, typically subchart paths in
	// umbrella charts. Paths use JSONPath-lite syntax: dot-separated, with
	// quoted bracket segments for keys containing dots or other special
	// characters (e.g. 'jupyterhub.singleuser.extraResource.limits["nvidia.com/gpu"]').
	// User-supplied spec.values at the same paths are overwritten by the
	// operator (a ResourcesInjected condition surfaces the override).
	// +optional
	ResourceInjection *ResourceInjectionMap `json:"resourceInjection,omitempty"`
}

type WorkspaceClassStatus struct {
	// Conditions represent the latest observations.
	// +patchMergeKey=type
	// +patchStrategy=merge
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`
	// ObservedGeneration is the .metadata.generation that was last reconciled.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// Valid indicates whether the referenced ServiceTemplate is available and
	// itself reports valid=true.
	Valid bool `json:"valid"`
	// ValidationError describes why the WorkspaceClass is not valid.
	// Empty when Valid is true.
	ValidationError string `json:"validationError,omitempty"`
}

type WorkspaceDeployment struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   WorkspaceDeploymentSpec   `json:"spec"`
	Status WorkspaceDeploymentStatus `json:"status,omitempty"`
}

type WorkspaceDeploymentList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []WorkspaceDeployment `json:"items"`
}

type WorkspaceDeploymentPhase string

type WorkspaceDeploymentSpec struct {
	// WorkspaceClassRef is the name of the cluster-scoped WorkspaceClass.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	WorkspaceClassRef string `json:"workspaceClassRef"`

	// ClusterDeploymentRef identifies the target child cluster.
	ClusterDeploymentRef ClusterDeploymentRef `json:"clusterDeploymentRef"`

	// Resources overrides the default resources from the WorkspaceClass.
	// +optional
	Resources *WorkspaceResourceSpec `json:"resources,omitempty"`

	// Values provides user-specified Helm values merged on top of class defaults.
	// +optional
	Values *apiextensionsv1.JSON `json:"values,omitempty"`

	// Suspend, when true, causes the operator to skip reconciliation.
	// +optional
	Suspend bool `json:"suspend,omitempty"`
}

type WorkspaceDeploymentStatus struct {
	// Phase is a human-readable summary of the deployment lifecycle.
	// +optional
	Phase WorkspaceDeploymentPhase `json:"phase,omitempty"`

	// Conditions represent the latest observations.
	// +patchMergeKey=type
	// +patchStrategy=merge
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// ObservedGeneration is the .metadata.generation that was last reconciled.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// ServiceEntryName is the name of the service entry added to the ClusterDeployment.
	// +optional
	ServiceEntryName string `json:"serviceEntryName,omitempty"`

	// ResolvedResources captures the effective resources after merging.
	// +optional
	ResolvedResources *WorkspaceResourceSpec `json:"resolvedResources,omitempty"`

	// Prerequisites reports the per-prerequisite install state. Only populated
	// when the resolved WorkspaceClass declares prerequisites.
	// +optional
	// +listType=map
	// +listMapKey=name
	Prerequisites []PrerequisiteStatus `json:"prerequisites,omitempty"`

	// Feasibility reports whether the cluster has enough free capacity to
	// deploy this workspace. Refreshed on every reconcile while the
	// workspace is being deployed; not updated once the workspace is Running.
	// +optional
	Feasibility *FeasibilityStatus `json:"feasibility,omitempty"`

	// Access lists the externally reachable endpoints of this workspace,
	// resolved by the routing provider once the workspace is Running.
	// +optional
	// +listType=map
	// +listMapKey=name
	Access []AccessEntry `json:"access,omitempty"`

	// FailureContext bundles operator-side failure forensics, populated on
	// every transition into Failed and cleared when the workspace recovers.
	// +optional
	FailureContext *FailureContext `json:"failureContext,omitempty"`

	// Message is a human-readable error or status detail.
	// +optional
	Message string `json:"message,omitempty"`
}

type WorkspaceResourceSpec struct {
	// Replicas is the number of pod-shaped instances the workspace deploys.
	// Defaults to 1.
	// +optional
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:default=1
	Replicas *int32 `json:"replicas,omitempty"`
	// PerReplica specifies resources requested per replica.
	PerReplica ResourceRequirements `json:"perReplica"`
}