v1alpha1

type AWSBedrockConfig struct {
	// credentialsSecret references a Secret in the operator namespace
	// (openshift-lightspeed) containing AWS credentials. The Secret must
	// contain the keys AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
	// +required
	CredentialsSecret SecretReference `json:"credentialsSecret,omitzero"`

	// region is the AWS region for the Bedrock endpoint.
	// Must begin with a lowercase letter and end with a lowercase
	// alphanumeric character. May contain lowercase letters, digits,
	// and hyphens (e.g., "us-east-1", "eu-west-2", "ap-southeast-1").
	// +required
	// +kubebuilder:validation:MinLength=2
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:XValidation:rule="self.matches('^[a-z][a-z0-9-]*[a-z0-9]$')",message="region must contain only lowercase letters, digits, and hyphens, start with a letter, and not end with a hyphen"
	Region string `json:"region,omitempty"`

	// url is an optional override for the AWS Bedrock API endpoint.
	// Only needed for custom deployments or API proxies.
	// Must be a valid HTTP or HTTPS URL with a hostname. Paths and query
	// parameters are allowed. Fragments and userinfo are not permitted.
	// Maximum 2048 characters.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=2048
	// +kubebuilder:validation:XValidation:rule="isURL(self) && url(self).getScheme() in ['http', 'https']",message="must use http or https scheme"
	// +kubebuilder:validation:XValidation:rule="isURL(self) && url(self).getHostname() != ”",message="must include a hostname"
	// +kubebuilder:validation:XValidation:rule="!self.contains('@')",message="userinfo is not allowed in URL"
	// +kubebuilder:validation:XValidation:rule="!self.contains('#')",message="fragments are not allowed in URL"
	URL string `json:"url,omitempty"`
}

type ActionOutcome string

type Agent struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is the standard object metadata.
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// spec defines the desired state of Agent.
	// +required
	Spec AgentSpec `json:"spec,omitzero"`

	// status defines the observed state of Agent.
	// +optional
	Status AgentStatus `json:"status,omitzero"`
}

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

type AgentSpec struct {
	// llmProvider references a cluster-scoped LLMProvider CR that supplies the
	// LLM backend for this agent tier.
	// +required
	LLMProvider LLMProviderReference `json:"llmProvider,omitzero"`

	// model is the LLM model identifier as recognized by the provider
	// (e.g., "claude-opus-4-6", "claude-haiku-4-5", "gpt-4o").
	// Must start with an alphanumeric character and may contain
	// alphanumerics, dots, hyphens, underscores, slashes, colons,
	// and at-signs. Maximum 256 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=256
	// +kubebuilder:validation:XValidation:rule="self.matches('^[a-zA-Z0-9][a-zA-Z0-9._\\\\-/:@]*$')",message="model must start with an alphanumeric character and contain only alphanumerics, dots, hyphens, underscores, slashes, colons, and at-signs"
	Model string `json:"model,omitempty"`

	// timeouts configures per-step and per-turn timeout limits.
	// When omitted, the agent sandbox uses its built-in defaults.
	// +optional
	Timeouts AgentTimeouts `json:"timeouts,omitzero"`

	// maxTurns is the maximum number of tool-use turns the agent may take
	// in a single step invocation. Prevents runaway loops.
	// When omitted, the agent sandbox uses its built-in default.
	// Minimum 1, maximum 500.
	// +optional
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=500
	MaxTurns int32 `json:"maxTurns,omitempty"`
}

type AgentStatus struct {
	// conditions represent the latest available observations of the
	// Agent's state. The Ready condition summarizes whether all
	// referenced resources (LLMProvider, Secrets) are present.
	// +listType=map
	// +listMapKey=type
	// +patchStrategy=merge
	// +patchMergeKey=type
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=8
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
}

type AgentTimeouts struct {
	// analysisSeconds is the timeout for the analysis step in seconds.
	// +optional
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=3600
	AnalysisSeconds int32 `json:"analysisSeconds,omitempty"`

	// executionSeconds is the timeout for the execution step in seconds.
	// +optional
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=3600
	ExecutionSeconds int32 `json:"executionSeconds,omitempty"`

	// verificationSeconds is the timeout for the verification step in seconds.
	// +optional
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=3600
	VerificationSeconds int32 `json:"verificationSeconds,omitempty"`

	// chatSeconds is the timeout for each chat turn with the LLM in seconds.
	// +optional
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=600
	ChatSeconds int32 `json:"chatSeconds,omitempty"`
}

type AnalysisApproval struct {
	// agent is the Agent CR for this step. Defaults to "default".
	// +optional
	// +default="default"
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:XValidation:rule="!format.dns1123Subdomain().validate(self).hasValue()",message="must be a valid DNS subdomain: lowercase alphanumeric characters, hyphens, and dots"
	Agent string `json:"agent,omitempty"`
}

type AnalysisOutput struct {
	// mode controls which built-in properties the analysis output schema
	// includes. Default includes all built-in properties (diagnosis,
	// proposal, summary, rbac, verification). Minimal includes only the
	// base structure (options array with title per option). Omit or set
	// to "Default" for standard remediation workflows.
	// +optional
	// +default="Default"
	Mode AnalysisOutputMode `json:"mode,omitempty"`

	// schema is a JSON Schema injected as a required "components"
	// property in each analysis output option. Use this to require
	// adapter-specific structured data beyond the base analysis schema.
	// +optional
	// +kubebuilder:validation:Schemaless
	// +kubebuilder:validation:Type=object
	// +kubebuilder:pruning:PreserveUnknownFields
	Schema *apiextensionsv1.JSONSchemaProps `json:"schema,omitempty"`
}

type AnalysisOutputMode string

type AnalysisResult struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is the standard object metadata.
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// spec contains the immutable identity fields for this result.
	// +required
	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="spec is immutable"
	Spec AnalysisResultSpec `json:"spec,omitzero"`

	// status contains result data and conditions.
	// +optional
	Status AnalysisResultStatus `json:"status,omitzero"`
}

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

type AnalysisResultSpec struct {
	// proposalName is the name of the parent Proposal in the same namespace.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	ProposalName string `json:"proposalName,omitempty"`
}

type AnalysisResultStatus struct {
	// conditions track the lifecycle of this result.
	// +listType=map
	// +listMapKey=type
	// +patchStrategy=merge
	// +patchMergeKey=type
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=8
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`

	// options contains the remediation options returned by the analysis agent.
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=10
	Options []RemediationOption `json:"options,omitempty"`

	// sandbox tracks the sandbox pod used for this analysis.
	// +optional
	Sandbox SandboxInfo `json:"sandbox,omitzero"`

	// failureReason is populated when the step failed due to a system error.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=8192
	FailureReason string `json:"failureReason,omitempty"`
}

type AnalysisStepStatus struct {
	// conditions for this step.
	// +listType=map
	// +listMapKey=type
	// +patchStrategy=merge
	// +patchMergeKey=type
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=8
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
	// sandbox tracks the sandbox used.
	// +optional
	Sandbox SandboxInfo `json:"sandbox,omitzero"`
	// results references AnalysisResult CRs, newest last.
	// Each entry corresponds to one analysis attempt.
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=20
	Results []StepResultRef `json:"results,omitempty"`
}

type AnthropicConfig struct {
	// credentialsSecret references a Secret in the operator namespace
	// (openshift-lightspeed) containing the Anthropic API credentials.
	// The Secret must contain the key ANTHROPIC_API_KEY.
	// +required
	CredentialsSecret SecretReference `json:"credentialsSecret,omitzero"`

	// url is an optional override for the Anthropic API endpoint.
	// Only needed for custom deployments or API proxies.
	// Must be a valid HTTP or HTTPS URL with a hostname. Paths and query
	// parameters are allowed. Fragments and userinfo are not permitted.
	// Maximum 2048 characters.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=2048
	// +kubebuilder:validation:XValidation:rule="isURL(self) && url(self).getScheme() in ['http', 'https']",message="must use http or https scheme"
	// +kubebuilder:validation:XValidation:rule="isURL(self) && url(self).getHostname() != ”",message="must include a hostname"
	// +kubebuilder:validation:XValidation:rule="!self.contains('@')",message="userinfo is not allowed in URL"
	// +kubebuilder:validation:XValidation:rule="!self.contains('#')",message="fragments are not allowed in URL"
	URL string `json:"url,omitempty"`
}

type ApprovalDecision string

type ApprovalMode string

type ApprovalPolicy struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is the standard object metadata.
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// spec defines the desired approval policy.
	// +required
	Spec ApprovalPolicySpec `json:"spec,omitzero"`
}

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

type ApprovalPolicySpec struct {
	// stages configures the approval mode for each workflow step.
	// Omitted steps default to Manual.
	// +optional
	// +listType=map
	// +listMapKey=name
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=4
	Stages []ApprovalPolicyStage `json:"stages,omitempty"`

	// maxAttempts sets the maximum number of execution retry attempts
	// allowed for proposals. When verification fails, the operator retries
	// execution up to this limit before escalating. Defaults to 1 if omitted.
	// +optional
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=3
	MaxAttempts int32 `json:"maxAttempts,omitempty"`

	// maxConcurrentProposals sets the maximum number of proposals the
	// operator reconciles concurrently. Higher values allow more proposals
	// to run in parallel but consume more cluster resources.
	// Defaults to 5 if omitted.
	// +optional
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=20
	// +default=5
	MaxConcurrentProposals int32 `json:"maxConcurrentProposals,omitempty"`
}

type ApprovalPolicyStage struct {
	// name is the workflow step this policy applies to.
	// Allowed values: Analysis, Execution, Verification, Escalation.
	// +required
	Name SandboxStep `json:"name,omitempty"`

	// approval controls whether this step auto-approves or requires
	// explicit user approval on the ProposalApproval resource.
	// Allowed values: Automatic (step runs without user approval),
	// Manual (step waits for explicit approval on ProposalApproval).
	// +required
	Approval ApprovalMode `json:"approval,omitempty"`
}

type ApprovalStage struct {
	// type identifies which workflow step this approval is for.
	// +required
	Type ApprovalStageType `json:"type,omitempty"`

	// decision indicates whether this stage is approved or denied.
	// Denying any stage terminates the entire proposal, even if
	// earlier stages were already approved. Once set to Denied,
	// it cannot be changed.
	// +optional
	Decision ApprovalDecision `json:"decision,omitempty"`

	// analysis contains approval parameters for the analysis step.
	// Required when type is Analysis.
	// +optional
	Analysis AnalysisApproval `json:"analysis,omitzero"`

	// execution contains approval parameters for the execution step.
	// Required when type is Execution.
	// +optional
	Execution ExecutionApproval `json:"execution,omitzero"`

	// verification contains approval parameters for the verification step.
	// Required when type is Verification.
	// +optional
	Verification VerificationApproval `json:"verification,omitzero"`

	// escalation contains approval parameters for the escalation step.
	// Required when type is Escalation.
	// +optional
	Escalation EscalationApproval `json:"escalation,omitzero"`
}

type ApprovalStageStatus struct {
	// conditions for this approval stage.
	// +listType=map
	// +listMapKey=type
	// +patchStrategy=merge
	// +patchMergeKey=type
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=8
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`

	// name identifies the workflow step.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name,omitempty"`
}

type ApprovalStageType string

type AzureOpenAIConfig struct {
	// credentialsSecret references a Secret in the operator namespace
	// (openshift-lightspeed) containing the Azure OpenAI API credentials.
	// The Secret must contain the key AZURE_OPENAI_API_KEY.
	// +required
	CredentialsSecret SecretReference `json:"credentialsSecret,omitzero"`

	// endpoint is the Azure OpenAI resource endpoint
	// (e.g., "https://my-resource.openai.azure.com").
	// Must be a valid HTTP or HTTPS URL with a hostname. Paths and query
	// parameters are allowed. Fragments and userinfo are not permitted.
	// Maximum 2048 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=2048
	// +kubebuilder:validation:XValidation:rule="isURL(self) && url(self).getScheme() in ['http', 'https']",message="must use http or https scheme"
	// +kubebuilder:validation:XValidation:rule="isURL(self) && url(self).getHostname() != ”",message="must include a hostname"
	// +kubebuilder:validation:XValidation:rule="!self.contains('@')",message="userinfo is not allowed in URL"
	// +kubebuilder:validation:XValidation:rule="!self.contains('#')",message="fragments are not allowed in URL"
	Endpoint string `json:"endpoint,omitempty"`

	// apiVersion is the Azure OpenAI API version. Azure API versions use
	// a date-based format: YYYY-MM-DD with an optional "-preview" suffix
	// (e.g., "2024-02-01", "2024-08-01-preview").
	// When omitted, the SDK default is used.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=32
	// +kubebuilder:validation:XValidation:rule="self.matches('^[0-9]{4}-[0-9]{2}-[0-9]{2}(-preview)?$')",message="apiVersion must be a date in YYYY-MM-DD format with an optional -preview suffix"
	APIVersion string `json:"apiVersion,omitempty"`

	// url is an optional override for the Azure OpenAI API endpoint.
	// Only needed for custom deployments or API proxies. This is separate
	// from the required 'endpoint' field which identifies the Azure resource.
	// Must be a valid HTTP or HTTPS URL with a hostname. Paths and query
	// parameters are allowed. Fragments and userinfo are not permitted.
	// Maximum 2048 characters.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=2048
	// +kubebuilder:validation:XValidation:rule="isURL(self) && url(self).getScheme() in ['http', 'https']",message="must use http or https scheme"
	// +kubebuilder:validation:XValidation:rule="isURL(self) && url(self).getHostname() != ”",message="must include a hostname"
	// +kubebuilder:validation:XValidation:rule="!self.contains('@')",message="userinfo is not allowed in URL"
	// +kubebuilder:validation:XValidation:rule="!self.contains('#')",message="fragments are not allowed in URL"
	URL string `json:"url,omitempty"`
}

type CheckResult string

type ConditionOutcome string

type ConfidenceLevel string

type DiagnosisResult struct {
	// summary is a Markdown-formatted diagnosis summary explaining the
	// problem, its symptoms, and the agent's findings. Maximum 8192 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=8192
	Summary string `json:"summary,omitempty"`
	// confidence is the agent's self-assessed confidence in its diagnosis.
	// Higher confidence generally correlates with clearer symptoms and
	// more deterministic root causes.
	// +required
	Confidence ConfidenceLevel `json:"confidence,omitempty"`
	// rootCause is a concise Markdown-formatted description of the identified
	// root cause (e.g., "OOMKilled due to memory limit of 256Mi").
	// Maximum 1024 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=1024
	RootCause string `json:"rootCause,omitempty"`
}

type EscalationApproval struct {
	// agent is the Agent CR for this step. Defaults to "default".
	// +optional
	// +default="default"
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:XValidation:rule="!format.dns1123Subdomain().validate(self).hasValue()",message="must be a valid DNS subdomain: lowercase alphanumeric characters, hyphens, and dots"
	Agent string `json:"agent,omitempty"`
}

type EscalationResult struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is the standard object metadata.
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// spec contains the immutable identity fields for this result.
	// +required
	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="spec is immutable"
	Spec EscalationResultSpec `json:"spec,omitzero"`

	// status contains result data and conditions.
	// +optional
	Status EscalationResultStatus `json:"status,omitzero"`
}

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

type EscalationResultSpec struct {
	// proposalName is the name of the parent Proposal in the same namespace.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	ProposalName string `json:"proposalName,omitempty"`
}

type EscalationResultStatus struct {
	// conditions track the lifecycle of this result.
	// +listType=map
	// +listMapKey=type
	// +patchStrategy=merge
	// +patchMergeKey=type
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=8
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`

	// summary is a Markdown-formatted escalation summary.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=32768
	Summary string `json:"summary,omitempty"`

	// content is freeform escalation content produced by the agent.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=65536
	Content string `json:"content,omitempty"`

	// sandbox tracks the sandbox pod used for this escalation.
	// +optional
	Sandbox SandboxInfo `json:"sandbox,omitzero"`

	// failureReason is populated when the step failed due to a system error.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=8192
	FailureReason string `json:"failureReason,omitempty"`
}

type EscalationStepStatus struct {
	// conditions for this step.
	// +listType=map
	// +listMapKey=type
	// +patchStrategy=merge
	// +patchMergeKey=type
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=8
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
	// sandbox tracks the sandbox used.
	// +optional
	Sandbox SandboxInfo `json:"sandbox,omitzero"`
	// results references EscalationResult CRs, newest last.
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=20
	Results []StepResultRef `json:"results,omitempty"`
}

type ExecutionAction struct {
	// type is the action category (e.g., "patch", "scale", "restart").
	// Maximum 256 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=256
	Type string `json:"type,omitempty"`
	// description is a Markdown-formatted explanation of what the agent did
	// (e.g., "Patched deployment/web to set memory limit to 512Mi").
	// Maximum 4096 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=4096
	Description string `json:"description,omitempty"`
	// outcome indicates whether this individual action succeeded.
	// Must be one of: Succeeded, Failed.
	// +required
	Outcome ActionOutcome `json:"outcome,omitempty"`
	// output is the command output or API response from the action.
	// Maximum 32768 characters.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=32768
	Output string `json:"output,omitempty"`
	// error is the error message if the action failed.
	// Maximum 8192 characters.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=8192
	Error string `json:"error,omitempty"`
}

type ExecutionApproval struct {
	// agent is the Agent CR for this step. Defaults to "default".
	// +optional
	// +default="default"
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:XValidation:rule="!format.dns1123Subdomain().validate(self).hasValue()",message="must be a valid DNS subdomain: lowercase alphanumeric characters, hyphens, and dots"
	Agent string `json:"agent,omitempty"`

	// option is the 0-based index into the analysis options array
	// selecting which remediation approach to execute.
	// +optional
	// +kubebuilder:validation:Minimum=0
	Option *int32 `json:"option,omitempty"`

	// maxAttempts is the number of execution retry attempts approved
	// for this proposal. Must not exceed ApprovalPolicy.spec.maxAttempts.
	// Defaults to 1 if unset.
	// +optional
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=3
	MaxAttempts int32 `json:"maxAttempts,omitempty"`
}

type ExecutionResult struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is the standard object metadata.
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// spec contains the immutable identity fields for this result.
	// +required
	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="spec is immutable"
	Spec ExecutionResultSpec `json:"spec,omitzero"`

	// status contains result data and conditions.
	// +optional
	Status ExecutionResultStatus `json:"status,omitzero"`
}

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

type ExecutionResultSpec struct {
	// proposalName is the name of the parent Proposal in the same namespace.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	ProposalName string `json:"proposalName,omitempty"`

	// retryIndex is the 0-based retry index within the current analysis.
	// First execution has retryIndex 0, first retry has retryIndex 1, etc.
	// +required
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=2
	RetryIndex *int32 `json:"retryIndex,omitempty"`
}

type ExecutionResultStatus struct {
	// conditions track the lifecycle of this result.
	// +listType=map
	// +listMapKey=type
	// +patchStrategy=merge
	// +patchMergeKey=type
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=8
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`

	// actionsTaken lists what the agent did.
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=100
	ActionsTaken []ExecutionAction `json:"actionsTaken,omitempty"`

	// verification is the lightweight inline verification the execution
	// agent performs immediately after completing its actions.
	// +optional
	Verification ExecutionVerification `json:"verification,omitzero"`

	// sandbox tracks the sandbox pod used for this execution.
	// +optional
	Sandbox SandboxInfo `json:"sandbox,omitzero"`

	// failureReason is populated when the step failed due to a system error.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=8192
	FailureReason string `json:"failureReason,omitempty"`
}

type ExecutionStepStatus struct {
	// conditions for this step.
	// +listType=map
	// +listMapKey=type
	// +patchStrategy=merge
	// +patchMergeKey=type
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=8
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
	// sandbox tracks the sandbox used.
	// +optional
	Sandbox SandboxInfo `json:"sandbox,omitzero"`
	// retryCount tracks how many times execution+verification has been
	// retried for the current analysis option. Reset when a new analysis
	// is run (initial or revision). The operator increments this on each
	// objective verification failure before retrying execution.
	// +optional
	// +kubebuilder:validation:Minimum=0
	RetryCount *int32 `json:"retryCount,omitempty"`
	// results references ExecutionResult CRs, newest last.
	// Each entry corresponds to one execution attempt (including retries).
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=20
	Results []StepResultRef `json:"results,omitempty"`
}

type ExecutionVerification struct {
	// conditionOutcome indicates whether the target condition improved
	// after the remediation (e.g., pod is no longer CrashLoopBackOff).
	// Must be one of: Improved, Unchanged, Degraded.
	// +required
	ConditionOutcome ConditionOutcome `json:"conditionOutcome,omitempty"`
	// summary is a Markdown-formatted summary of the inline verification.
	// Maximum 4096 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=4096
	Summary string `json:"summary,omitempty"`
}

type GoogleCloudVertexConfig struct {
	// credentialsSecret references a Secret in the operator namespace
	// (openshift-lightspeed) containing a GCP service account JSON key.
	// The Secret must contain the key GOOGLE_APPLICATION_CREDENTIALS.
	// +required
	CredentialsSecret SecretReference `json:"credentialsSecret,omitzero"`

	// projectID is the Google Cloud Project ID where Vertex AI is enabled.
	// A Project ID is a globally unique identifier that must be 6 to 30
	// characters in length, can only contain lowercase letters, digits, and
	// hyphens, must start with a letter, and cannot end with a hyphen.
	// +required
	// +kubebuilder:validation:MinLength=6
	// +kubebuilder:validation:MaxLength=30
	// +kubebuilder:validation:XValidation:rule="self.matches('^[a-z][a-z0-9-]*[a-z0-9]$')",message="projectID must start with a lowercase letter, contain only lowercase letters, digits, and hyphens, and cannot end with a hyphen"
	ProjectID string `json:"projectID,omitempty"`

	// region is the GCP region for the Vertex AI endpoint.
	// Must begin with a lowercase letter and end with a lowercase
	// alphanumeric character. May contain lowercase letters, digits,
	// and hyphens (e.g., "us-central1", "europe-west4", "asia-southeast1").
	// +required
	// +kubebuilder:validation:MinLength=2
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:XValidation:rule="self.matches('^[a-z][a-z0-9-]*[a-z0-9]$')",message="region must contain only lowercase letters, digits, and hyphens, start with a letter, and not end with a hyphen"
	Region string `json:"region,omitempty"`

	// url is an optional override for the Vertex AI API endpoint.
	// Only needed for custom deployments or API proxies.
	// Must be a valid HTTP or HTTPS URL with a hostname. Paths and query
	// parameters are allowed. Fragments and userinfo are not permitted.
	// Maximum 2048 characters.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=2048
	// +kubebuilder:validation:XValidation:rule="isURL(self) && url(self).getScheme() in ['http', 'https']",message="must use http or https scheme"
	// +kubebuilder:validation:XValidation:rule="isURL(self) && url(self).getHostname() != ”",message="must include a hostname"
	// +kubebuilder:validation:XValidation:rule="!self.contains('@')",message="userinfo is not allowed in URL"
	// +kubebuilder:validation:XValidation:rule="!self.contains('#')",message="fragments are not allowed in URL"
	URL string `json:"url,omitempty"`
}

type LLMProvider struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is the standard object metadata.
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// spec defines the desired state of LLMProvider.
	// +required
	Spec LLMProviderSpec `json:"spec,omitzero"`
}

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

type LLMProviderReference struct {
	// name of the LLMProvider. Must be a valid RFC 1123 DNS subdomain.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:XValidation:rule="!format.dns1123Subdomain().validate(self).hasValue()",message="must be a valid DNS subdomain: lowercase alphanumeric characters, hyphens, and dots"
	Name string `json:"name,omitempty"`
}

type LLMProviderSpec struct {
	// type is a required field that configures which LLM provider backend
	// should be used.
	//
	// Allowed values are Anthropic, GoogleCloudVertex, OpenAI, AzureOpenAI,
	// and AWSBedrock.
	//
	// When set to Anthropic, agents referencing this provider will use the
	// Anthropic API directly, and the 'anthropic' field must be configured.
	//
	// When set to GoogleCloudVertex, agents referencing this provider will
	// use Google Cloud Vertex AI, and the 'googleCloudVertex' field must be
	// configured.
	//
	// When set to OpenAI, agents referencing this provider will use an
	// OpenAI-compatible API, and the 'openAI' field must be configured.
	//
	// When set to AzureOpenAI, agents referencing this provider will use
	// the Azure OpenAI Service, and the 'azureOpenAI' field must be
	// configured.
	//
	// When set to AWSBedrock, agents referencing this provider will use
	// AWS Bedrock, and the 'awsBedrock' field must be configured.
	// +required
	Type LLMProviderType `json:"type,omitempty"`

	// anthropic contains Anthropic-specific configuration.
	// Required when type is "Anthropic".
	// +optional
	Anthropic AnthropicConfig `json:"anthropic,omitzero"`

	// googleCloudVertex contains Google Cloud Vertex AI-specific configuration.
	// Required when type is "GoogleCloudVertex".
	// +optional
	GoogleCloudVertex GoogleCloudVertexConfig `json:"googleCloudVertex,omitzero"`

	// openAI contains OpenAI-specific configuration.
	// Required when type is "OpenAI".
	// +optional
	OpenAI OpenAIConfig `json:"openAI,omitzero"`

	// azureOpenAI contains Azure OpenAI Service-specific configuration.
	// Required when type is "AzureOpenAI".
	// +optional
	AzureOpenAI AzureOpenAIConfig `json:"azureOpenAI,omitzero"`

	// awsBedrock contains AWS Bedrock-specific configuration.
	// Required when type is "AWSBedrock".
	// +optional
	AWSBedrock AWSBedrockConfig `json:"awsBedrock,omitzero"`
}

type LLMProviderType string

type MCPHeader struct {
	// name of the header (e.g., "Authorization", "X-API-Key").
	// Must be at least 1 character, containing only letters, digits, and hyphens.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:XValidation:rule="self.matches('^[A-Za-z][A-Za-z0-9-]*$')",message="name must start with a letter and contain only letters, digits, and hyphens"
	Name string `json:"name,omitempty"`

	// valueFrom is the source of the header value.
	// +required
	ValueFrom MCPHeaderValueSource `json:"valueFrom,omitzero"`
}

type MCPHeaderSourceType string

type MCPHeaderValueSource struct {
	// type specifies the source type for the header value. Allowed values:
	//   - "Secret"     — reads the value from a Kubernetes Secret (use for
	//     API keys and tokens). Requires the secret field to be set.
	//   - "ServiceAccountToken" — auto-injects a Kubernetes service account token
	//     (for MCP servers that accept K8s auth).
	//   - "Client"     — the value is provided by the calling client at
	//     runtime (e.g., forwarded from a user session).
	// +required
	Type MCPHeaderSourceType `json:"type,omitempty"`

	// secret references a Secret containing the header value.
	// Required when type is "Secret".
	// +optional
	Secret SecretReference `json:"secret,omitzero"`
}

type MCPServerConfig struct {
	// name of the MCP server. Must start with a letter and contain only
	// lowercase alphanumeric characters and hyphens. Must be 1-253 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:XValidation:rule="self.matches('^[a-z][a-z0-9-]*$')",message="name must start with a lowercase letter and contain only lowercase alphanumerics and hyphens"
	Name string `json:"name,omitempty"`

	// url of the MCP server (HTTP/HTTPS). Must be an HTTP or HTTPS URL,
	// maximum 2048 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=2048
	// +kubebuilder:validation:XValidation:rule="isURL(self) && url(self).getScheme() in ['http', 'https']",message="url must be a valid HTTP or HTTPS URL"
	URL string `json:"url,omitempty"`

	// timeoutSeconds is the per-request timeout for calls to this MCP server,
	// in seconds. Default is 5.
	// Valid range: 1-300.
	// +optional
	// +default=5
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=300
	TimeoutSeconds int32 `json:"timeoutSeconds,omitempty"`

	// headers to send to the MCP server. Maximum 20 items.
	// +optional
	// +listType=map
	// +listMapKey=name
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=20
	Headers []MCPHeader `json:"headers,omitempty"`
}

type OpenAIConfig struct {
	// credentialsSecret references a Secret in the operator namespace
	// (openshift-lightspeed) containing the OpenAI API credentials.
	// The Secret must contain the key OPENAI_API_KEY.
	// +required
	CredentialsSecret SecretReference `json:"credentialsSecret,omitzero"`

	// url is an optional override for the OpenAI API endpoint.
	// Only needed for custom deployments or API proxies.
	// Must be a valid HTTP or HTTPS URL with a hostname. Paths and query
	// parameters are allowed. Fragments and userinfo are not permitted.
	// Maximum 2048 characters.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=2048
	// +kubebuilder:validation:XValidation:rule="isURL(self) && url(self).getScheme() in ['http', 'https']",message="must use http or https scheme"
	// +kubebuilder:validation:XValidation:rule="isURL(self) && url(self).getHostname() != ”",message="must include a hostname"
	// +kubebuilder:validation:XValidation:rule="!self.contains('@')",message="userinfo is not allowed in URL"
	// +kubebuilder:validation:XValidation:rule="!self.contains('#')",message="fragments are not allowed in URL"
	URL string `json:"url,omitempty"`
}

type Proposal struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is the standard object metadata.
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// spec defines the desired state of Proposal.
	// +required
	Spec ProposalSpec `json:"spec,omitzero"`

	// status defines the observed state of Proposal.
	// +optional
	Status ProposalStatus `json:"status,omitzero"`
}

type ProposalApproval struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is the standard object metadata.
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// spec defines the desired approval state.
	// +optional
	Spec ProposalApprovalSpec `json:"spec,omitzero"`

	// status defines the observed approval state.
	// +optional
	Status ProposalApprovalStatus `json:"status,omitzero"`
}

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

type ProposalApprovalSpec struct {
	// stages lists the approved (or denied) workflow steps. Each entry is
	// a discriminated union keyed by type. Users add stages one at a time
	// via patch as they approve each step.
	// +optional
	// +listType=map
	// +listMapKey=type
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=4
	Stages []ApprovalStage `json:"stages,omitempty"`
}

type ProposalApprovalStatus struct {
	// stages contains the per-stage approval status set by the controller.
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=4
	Stages []ApprovalStageStatus `json:"stages,omitempty"`
}

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

type ProposalPhase string

type ProposalResult struct {
	// description is a Markdown-formatted summary of the overall remediation
	// approach. Maximum 8192 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=8192
	Description string `json:"description,omitempty"`
	// actions is the ordered list of discrete actions the agent proposes.
	// Maximum 50 items.
	// +required
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=50
	Actions []ProposedAction `json:"actions,omitempty"`
	// risk is the agent's assessment of how risky the remediation is.
	// Critical-risk proposals typically require explicit human review.
	// +required
	Risk RiskLevel `json:"risk,omitempty"`
	// reversible indicates whether the remediation can be rolled back
	// if something goes wrong. See rollbackPlan for details.
	// Must be one of: Reversible, Irreversible, Partial.
	// +optional
	Reversible Reversibility `json:"reversible,omitempty"`
	// estimatedImpact is a Markdown-formatted description of the expected
	// impact of the remediation on the system
	// (e.g., "Brief pod restart, ~30s downtime").
	// Maximum 1024 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=1024
	EstimatedImpact string `json:"estimatedImpact,omitempty"`
	// rollbackPlan describes how to undo the remediation if execution fails
	// or causes unexpected issues. Only the execution step mutates cluster
	// state, so rollback lives here alongside the actions it would undo.
	// +optional
	RollbackPlan RollbackPlan `json:"rollbackPlan,omitzero"`
}

type ProposalSpec struct {
	// request is the user's original request, alert description, or a
	// description of what triggered this proposal. This text is passed to
	// the analysis agent as the primary input.
	//
	// Immutable: Proposals are run-to-completion (like Jobs). To change
	// the request, create a new Proposal. Use spec.revisionFeedback for
	// iterative feedback on an existing analysis.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=32768
	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="request is immutable after creation"
	Request string `json:"request,omitempty"`

	// targetNamespaces are the Kubernetes namespace(s) this proposal
	// operates on. Used for RBAC scoping and context to the analysis agent.
	//
	// When omitted, the proposal is not namespace-scoped — the analysis
	// agent determines the relevant namespaces from the request context.
	// Adapters (AlertManager, ACS) typically set this automatically from
	// the source event.
	//
	// Immutable: RBAC scoping is fixed at creation. Changing target
	// namespaces mid-flight would invalidate the analysis and any
	// granted execution RBAC.
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=50
	// +kubebuilder:validation:XValidation:rule="self.all(ns, !format.dns1123Label().validate(ns).hasValue())",message="each namespace must be a valid DNS label"
	// +kubebuilder:validation:items:MinLength=1
	// +kubebuilder:validation:items:MaxLength=63
	TargetNamespaces []string `json:"targetNamespaces,omitempty"`

	// analysisOutput configures the analysis step's structured output.
	// The mode field controls which built-in properties are included
	// (Default: all; Minimal: only title). The schema field optionally
	// defines adapter-specific structured data injected as "components".
	//
	// When omitted, the analysis uses the full default schema with all
	// built-in properties and no custom components.
	//
	// Immutable: the output contract is fixed at creation.
	// +optional
	AnalysisOutput AnalysisOutput `json:"analysisOutput,omitzero"`

	// tools defines the default tools for all steps: skills images,
	// MCP servers, and required secrets. Per-step tools
	// (analysis.tools, execution.tools, verification.tools) replace
	// this default for individual steps.
	//
	// Immutable: the skills and secrets available to the agent are
	// fixed at creation. Changing tools mid-flight could violate the
	// assumptions of an in-progress analysis or execution.
	// +optional
	Tools ToolsSpec `json:"tools,omitzero"`

	// analysis defines per-step configuration for the analysis step,
	// including which agent handles it and any per-step tools.
	//
	// Immutable: agent and per-step tools are fixed at creation.
	// +required
	Analysis ProposalStep `json:"analysis,omitzero"`

	// execution defines per-step configuration for the execution step.
	// Omit to skip execution (advisory/assisted patterns).
	//
	// Immutable: agent and per-step tools are fixed at creation.
	// +optional
	Execution ProposalStep `json:"execution,omitzero"`

	// verification defines per-step configuration for the verification step.
	// Omit to skip verification.
	//
	// Immutable: agent and per-step tools are fixed at creation.
	// +optional
	Verification ProposalStep `json:"verification,omitzero"`

	// revisionFeedback is the user's free-text feedback requesting changes
	// to the analysis. Patching this field bumps metadata.generation, which
	// the operator detects (generation > observedGeneration) and triggers
	// re-analysis with the feedback appended to the original request.
	//
	// Mutable: this is the only mutable spec field. All other spec fields
	// are immutable via CEL rules, so generation changes signal revision.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=32768
	RevisionFeedback string `json:"revisionFeedback,omitempty"`
}

type ProposalStatus struct {
	// conditions represent the latest available observations using the
	// standard Kubernetes condition pattern. Condition types include:
	// Analyzed, Approved, Executed, Verified, and Escalated.
	// +listType=map
	// +listMapKey=type
	// +patchStrategy=merge
	// +patchMergeKey=type
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=8
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`

	// steps contains the per-step observed state (analysis, execution,
	// verification). Each step independently tracks its timing, sandbox
	// info, and references to result CRs.
	// +optional
	Steps StepsStatus `json:"steps,omitzero"`
}

type ProposalStep struct {
	// agent is the name of the cluster-scoped Agent CR to use for this step.
	// Defaults to "default" when omitted.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:XValidation:rule="!format.dns1123Subdomain().validate(self).hasValue()",message="must be a valid DNS subdomain: lowercase alphanumeric characters, hyphens, and dots"
	Agent string `json:"agent,omitempty"`

	// tools provides per-step tools that replace the shared spec.tools
	// for this step. Use this when different steps need different skills.
	// +optional
	Tools ToolsSpec `json:"tools,omitzero"`
}

type ProposedAction struct {
	// type is the action category (e.g., "patch", "scale", "restart",
	// "create", "delete", "rollout"). Free-form string to allow agents
	// to express domain-specific action types. Must be 1-256 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=256
	Type string `json:"type,omitempty"`
	// description is a Markdown-formatted explanation of what this action
	// will do (e.g., "Increase memory limit from 256Mi to 512Mi").
	// Maximum 4096 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=4096
	Description string `json:"description,omitempty"`
}

type RBACResult struct {
	// namespaceScoped are rules that will be applied via Role + RoleBinding
	// in the proposal's target namespaces. These are the most common rules.
	// Maximum 50 items.
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=50
	NamespaceScoped []RBACRule `json:"namespaceScoped,omitempty"`
	// clusterScoped are rules that will be applied via ClusterRole +
	// ClusterRoleBinding. Used when the agent needs cross-namespace or
	// non-namespaced resource access (e.g., reading nodes, CRDs).
	// Maximum 50 items.
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=50
	ClusterScoped []RBACRule `json:"clusterScoped,omitempty"`
}

type RBACRule struct {
	// namespace is the target namespace for namespace-scoped rules.
	// Must match one of the proposal's targetNamespaces. Ignored for
	// cluster-scoped rules. Validation is deferred to the operator's
	// policy engine at runtime. Must be a valid RFC 1123 DNS label.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:XValidation:rule="!format.dns1123Label().validate(self).hasValue()",message="must be a valid DNS label: lowercase alphanumeric characters and hyphens, starting with an alphabetic character and ending with an alphanumeric character"
	Namespace string `json:"namespace,omitempty"`
	// apiGroups are the API groups for this rule (e.g., "", "apps", "batch").
	// The empty string "" represents the core API group (pods, services, etc.).
	// Maximum 20 items, each up to 253 characters.
	// +required
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=20
	// +kubebuilder:validation:items:MaxLength=253
	APIGroups []string `json:"apiGroups,omitempty"` //nolint:kubeapilinter // empty string "" is a valid core API group
	// resources are the resource types (e.g., "pods", "deployments").
	// Maximum 20 items.
	// +required
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=20
	// +kubebuilder:validation:items:MinLength=1
	// +kubebuilder:validation:items:MaxLength=253
	Resources []string `json:"resources,omitempty"`
	// resourceNames restricts the rule to specific named resources.
	// When empty, the rule applies to all resources of the given type.
	// Maximum 50 items.
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=50
	// +kubebuilder:validation:items:MinLength=1
	// +kubebuilder:validation:items:MaxLength=253
	ResourceNames []string `json:"resourceNames,omitempty"`
	// verbs are the allowed operations (e.g., "get", "patch", "delete").
	// Maximum 10 items.
	// +required
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=10
	// +kubebuilder:validation:items:MinLength=1
	// +kubebuilder:validation:items:MaxLength=63
	Verbs []string `json:"verbs,omitempty"`
	// justification is a Markdown-formatted explanation of why this
	// permission is needed for the remediation
	// (e.g., "Need to patch deployment to increase memory limit").
	// Required for audit and policy enforcement. Maximum 1024 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=1024
	Justification string `json:"justification,omitempty"`
}

type RemediationOption struct {
	// title is a short Markdown-formatted name for this option
	// (e.g., "Increase memory limit", "Restart with backoff").
	// Must be 1-256 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=256
	Title string `json:"title,omitempty"`
	// summary is an optional Markdown-formatted one-line summary for
	// collapsed views in the console UI. Maximum 1024 characters.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=1024
	Summary string `json:"summary,omitempty"`
	// diagnosis contains the root cause analysis specific to this option.
	// Present when analysisOutput mode is Default (or omitted). Omitted
	// when mode is Minimal.
	// +optional
	Diagnosis DiagnosisResult `json:"diagnosis,omitzero"`
	// proposal contains the remediation plan for this option.
	// Present when analysisOutput mode is Default (or omitted). Omitted
	// when mode is Minimal without an execution step.
	// +optional
	Proposal ProposalResult `json:"proposal,omitzero"`
	// verification contains the verification plan. Omitted when
	// verification is skipped in the workflow.
	// +optional
	Verification VerificationPlan `json:"verification,omitzero"`
	// rbac contains the RBAC permissions the execution agent will need.
	// The operator's policy engine validates these before creating the
	// actual Kubernetes RBAC resources. Omitted for advisory-only options.
	// +optional
	RBAC RBACResult `json:"rbac,omitzero"`
	// components contains optional adapter-defined structured data whose
	// shape is determined by spec.analysisOutput.schema on the Proposal.
	// The operator passes this through to the AnalysisResult CR; the
	// console renders it using adapter-specific UI components.
	// +optional
	// +kubebuilder:validation:Schemaless
	// +kubebuilder:pruning:PreserveUnknownFields
	Components *apiextensionsv1.JSON `json:"components,omitempty"`
}

type Reversibility string

type RiskLevel string

type RollbackPlan struct {
	// description is a Markdown-formatted explanation of the rollback strategy.
	// Must be 1-4096 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=4096
	Description string `json:"description,omitempty"`
	// command is the rollback command or steps to execute.
	// Maximum 4096 characters.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=4096
	Command string `json:"command,omitempty"`
}

type SandboxInfo struct {
	// claimName is the name of the SandboxClaim resource that owns the
	// sandbox pod. Maximum 253 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	ClaimName string `json:"claimName,omitempty"`
	// namespace is the namespace where the SandboxClaim and its pod live.
	// Must be a valid RFC 1123 DNS label.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:XValidation:rule="!format.dns1123Label().validate(self).hasValue()",message="must be a valid DNS label: lowercase alphanumeric characters and hyphens, starting with an alphabetic character and ending with an alphanumeric character"
	Namespace string `json:"namespace,omitempty"`
}

type SandboxStep string

type SecretMountEnvVarConfig struct {
	// name is the environment variable name (e.g., "GITHUB_TOKEN").
	// Must be uppercase letters, digits, and underscores, starting
	// with a letter or underscore.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=256
	// +kubebuilder:validation:XValidation:rule="self.matches('^[A-Z_][A-Z0-9_]*$')",message="must be a valid environment variable name: uppercase letters, digits, and underscores, starting with a letter or underscore"
	Name string `json:"name,omitempty"`
}

type SecretMountFilePathConfig struct {
	// path is the absolute file path (e.g., "/etc/secrets/tls.crt").
	// Must start with a forward slash.
	// +required
	// +kubebuilder:validation:MinLength=2
	// +kubebuilder:validation:MaxLength=512
	// +kubebuilder:validation:XValidation:rule="self.startsWith('/')",message="path must be an absolute path starting with '/'"
	Path string `json:"path,omitempty"`
}

type SecretMountSpec struct {
	// type specifies how the secret is exposed. Allowed values: "EnvVar",
	// "FilePath".
	//
	// When set to EnvVar, the secret value is injected as an environment
	// variable, and the 'envVar' field must be configured.
	//
	// When set to FilePath, the secret is mounted as a file, and the
	// 'filePath' field must be configured.
	// +required
	Type SecretMountType `json:"type,omitempty"`

	// envVar configures environment variable injection.
	// Required when type is "EnvVar".
	// +optional
	EnvVar SecretMountEnvVarConfig `json:"envVar,omitzero"`

	// filePath configures file mount.
	// Required when type is "FilePath".
	// +optional
	FilePath SecretMountFilePathConfig `json:"filePath,omitzero"`
}

type SecretMountType string

type SecretReference struct {
	// name of the Secret. Must be a valid RFC 1123 DNS subdomain.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:XValidation:rule="!format.dns1123Subdomain().validate(self).hasValue()",message="must be a valid DNS subdomain: lowercase alphanumeric characters, hyphens, and dots"
	Name string `json:"name,omitempty"`
}

type SecretRequirement struct {
	// name of the Secret (must exist in the operator namespace).
	// Must be a valid RFC 1123 DNS subdomain.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:XValidation:rule="!format.dns1123Subdomain().validate(self).hasValue()",message="must be a valid DNS subdomain: lowercase alphanumeric characters, hyphens, and dots"
	Name string `json:"name,omitempty"`

	// description explains what this secret is used for, helping the
	// cluster admin understand what credentials to provide.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=1024
	Description string `json:"description,omitempty"`

	// mountAs specifies how the secret is exposed in the sandbox pod.
	// +required
	MountAs SecretMountSpec `json:"mountAs,omitzero"`
}

type SkillsSource struct {
	// image is the OCI image reference containing skills.
	// The operator mounts this as a Kubernetes image volume (requires K8s 1.34+).
	// Must be a valid OCI image pullspec: a domain, followed by a repository path,
	// ending with either a tag (:tag) or a digest (@algorithm:hex).
	// Must be 1-512 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=512
	// +kubebuilder:validation:XValidation:rule="self.matches('^([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])((\\\\.([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]))+)?(:[0-9]+)?\\\\b')",message="must start with a valid domain. valid domains must be alphanumeric characters (lowercase and uppercase) separated by the '.' character."
	// +kubebuilder:validation:XValidation:rule="self.find('(/[a-z0-9]+((([._]|__|[-]*)[a-z0-9]+)+)?((/[a-z0-9]+((([._]|__|[-]*)[a-z0-9]+)+)?)+)?)') != ”",message="a valid name is required. valid names must contain lowercase alphanumeric characters separated only by the '.', '_', '__', '-' characters."
	// +kubebuilder:validation:XValidation:rule="self.find('(@.*:)') != ” || self.find(':.*$') != ”",message="must end with a digest or a tag"
	// +kubebuilder:validation:XValidation:rule="self.find('(@.*:)') == ” ? (self.find(':.*$') != ” ? self.find(':.*$').substring(1).size() <= 127 : true) : true",message="tag must not be more than 127 characters"
	// +kubebuilder:validation:XValidation:rule="self.find('(@.*:)') == ” ? (self.find(':.*$') != ” ? self.find(':.*$').matches(':[\\\\w][\\\\w.-]*$') : true) : true",message="tag is invalid. valid tags must begin with a word character followed by word characters, '.', or '-'"
	// +kubebuilder:validation:XValidation:rule="self.find('(@.*:)') != ” ? self.find('(@.*:)').matches('(@[A-Za-z][A-Za-z0-9]*([_+.][A-Za-z][A-Za-z0-9]*)*[:])') : true",message="digest algorithm is not valid. valid algorithms must start with an alpha character followed by alphanumeric characters and may contain '-', '_', '+', and '.' characters."
	// +kubebuilder:validation:XValidation:rule="self.find('(@.*:)') != ” ? self.find(':.*$').substring(1).size() >= 32 : true",message="digest must be at least 32 characters"
	// +kubebuilder:validation:XValidation:rule="self.find('(@.*:)') != ” ? self.find(':.*$').matches(':[0-9A-Fa-f]*$') : true",message="digest must only contain hex characters (A-F, a-f, 0-9)"
	Image string `json:"image,omitempty"`

	// paths specifies which directories from the image are mounted.
	// Each path is mounted as a separate subPath volumeMount into the agent's
	// skills directory. The last segment of each path becomes the mount name
	// (e.g., "/skills/prometheus" mounts as "prometheus").
	//
	// Each path must be an absolute file path: starts with "/", no ".."
	// or "." segments, no double slashes, no trailing slash, and only
	// alphanumeric characters, hyphens, underscores, dots, and slashes.
	//
	// Maximum 50 items.
	// +required
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=50
	// +kubebuilder:validation:XValidation:rule="self.all(p, p.size() >= 2 && p.size() <= 512)",message="each path must be 2-512 characters"
	// +kubebuilder:validation:XValidation:rule="self.all(p, p.startsWith('/'))",message="each path must be absolute (start with '/')"
	// +kubebuilder:validation:XValidation:rule="self.all(p, !p.endsWith('/'))",message="paths must not end with '/'"
	// +kubebuilder:validation:XValidation:rule="self.all(p, !p.contains('//'))",message="paths must not contain double slashes"
	// +kubebuilder:validation:XValidation:rule="self.all(p, !p.contains('/../') && !p.endsWith('/..') && !p.contains('/./') && !p.endsWith('/.'))",message="paths must not contain '.' or '..' segments"
	// +kubebuilder:validation:XValidation:rule="self.all(p, p.matches('^[a-zA-Z0-9/_.-]+$'))",message="paths may only contain alphanumeric characters, '/', '_', '.', and '-'"
	// +kubebuilder:validation:items:MinLength=2
	// +kubebuilder:validation:items:MaxLength=512
	Paths []string `json:"paths"`
}

type StepPhase string

type StepResultRef struct {
	// name is the name of the result CR.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name,omitempty"`
	// outcome indicates the result of this step attempt.
	// Must be one of: Succeeded, Failed.
	// +required
	Outcome ActionOutcome `json:"outcome,omitempty"`
}

type StepsStatus struct {
	// analysis is the observed state of the analysis step.
	// +optional
	Analysis AnalysisStepStatus `json:"analysis,omitzero"`
	// execution is the observed state of the execution step.
	// +optional
	Execution ExecutionStepStatus `json:"execution,omitzero"`
	// verification is the observed state of the verification step.
	// +optional
	Verification VerificationStepStatus `json:"verification,omitzero"`
	// escalation is the observed state of the escalation step.
	// +optional
	Escalation EscalationStepStatus `json:"escalation,omitzero"`
}

type ToolsSpec struct {
	// skills defines one or more OCI images containing skills to mount
	// in the agent's sandbox pod. The operator creates Kubernetes image
	// volumes (requires K8s 1.34+) and mounts them into the agent's
	// skills directory. Each image must be unique within the list.
	// +optional
	// +listType=map
	// +listMapKey=image
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=20
	Skills []SkillsSource `json:"skills,omitempty"`

	// mcpServers defines external MCP (Model Context Protocol) servers the
	// agent can connect to for additional tools and context.
	// +optional
	// +listType=map
	// +listMapKey=name
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=20
	MCPServers []MCPServerConfig `json:"mcpServers,omitempty"`

	// requiredSecrets declares Kubernetes Secrets that the sandbox pod
	// needs at runtime. The cluster admin creates the actual Secrets
	// in the same namespace as the Proposal.
	// +optional
	// +listType=map
	// +listMapKey=name
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=20
	RequiredSecrets []SecretRequirement `json:"requiredSecrets,omitempty"`
}

type VerificationApproval struct {
	// agent is the Agent CR for this step. Defaults to "default".
	// +optional
	// +default="default"
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:XValidation:rule="!format.dns1123Subdomain().validate(self).hasValue()",message="must be a valid DNS subdomain: lowercase alphanumeric characters, hyphens, and dots"
	Agent string `json:"agent,omitempty"`
}

type VerificationPlan struct {
	// description is a Markdown-formatted summary of the verification approach.
	// Maximum 4096 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=4096
	Description string `json:"description,omitempty"`
	// steps is the ordered list of verification checks to run.
	// Maximum 20 items.
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=20
	Steps []VerificationStep `json:"steps,omitempty"`
}

type VerificationResult struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is the standard object metadata.
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// spec contains the immutable identity fields for this result.
	// +required
	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="spec is immutable"
	Spec VerificationResultSpec `json:"spec,omitzero"`

	// status contains result data and conditions.
	// +optional
	Status VerificationResultStatus `json:"status,omitzero"`
}

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

type VerificationResultSpec struct {
	// proposalName is the name of the parent Proposal in the same namespace.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	ProposalName string `json:"proposalName,omitempty"`

	// retryIndex is the 0-based retry index within the current analysis.
	// +required
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=2
	RetryIndex *int32 `json:"retryIndex,omitempty"`
}

type VerificationResultStatus struct {
	// conditions track the lifecycle of this result.
	// +listType=map
	// +listMapKey=type
	// +patchStrategy=merge
	// +patchMergeKey=type
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=8
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`

	// checks contains individual verification check results.
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=50
	Checks []VerifyCheck `json:"checks,omitempty"`

	// summary is a Markdown-formatted verification summary.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=32768
	Summary string `json:"summary,omitempty"`

	// sandbox tracks the sandbox pod used for this verification.
	// +optional
	Sandbox SandboxInfo `json:"sandbox,omitzero"`

	// failureReason is populated when the step failed due to a system error.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=8192
	FailureReason string `json:"failureReason,omitempty"`
}

type VerificationStep struct {
	// name is a short identifier for this check (e.g., "pod-running").
	// Must be 1-253 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name,omitempty"`
	// command is the command or API call to run for this check
	// (e.g., "oc get pod -n production -l app=web -o jsonpath='{.items[0].status.phase}'").
	// Maximum 4096 characters.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=4096
	Command string `json:"command,omitempty"`
	// expected is the expected output or condition
	// (e.g., "Running", "ready=true"). Maximum 1024 characters.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=1024
	Expected string `json:"expected,omitempty"`
	// type categorizes the check (e.g., "command", "metric", "condition").
	// Must be 1-256 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=256
	Type string `json:"type,omitempty"`
}

type VerificationStepStatus struct {
	// conditions for this step.
	// +listType=map
	// +listMapKey=type
	// +patchStrategy=merge
	// +patchMergeKey=type
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=8
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
	// sandbox tracks the sandbox used.
	// +optional
	Sandbox SandboxInfo `json:"sandbox,omitzero"`
	// results references VerificationResult CRs, newest last.
	// Each entry corresponds to one verification attempt (including retries).
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=20
	Results []StepResultRef `json:"results,omitempty"`
}

type VerifyCheck struct {
	// name is the check identifier, matching the VerificationStep name.
	// Maximum 253 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name,omitempty"`
	// source is what performed the check (e.g., "oc", "promql", "curl").
	// Maximum 256 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=256
	Source string `json:"source,omitempty"`
	// value is the actual observed value (e.g., "Running", "3 replicas").
	// Maximum 4096 characters.
	// +required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=4096
	Value string `json:"value,omitempty"`
	// result indicates whether the check's observed value matches
	// the expected value. Must be one of: Passed, Failed.
	// +required
	Result CheckResult `json:"result,omitempty"`
}