refs

type EngramReference struct {
	ObjectReference `json:",inline"`
	// Version pins the reference to a specific Engram version.
	// +kubebuilder:validation:MaxLength=64
	// +optional
	Version string     `json:"version,omitempty"`
	UID     *types.UID `json:"uid,omitempty"`
}

type EngramTemplateReference struct {
	// Name of the referenced EngramTemplate.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name"`

	// Version pins the reference to a specific EngramTemplate version.
	// +kubebuilder:validation:MaxLength=64
	// +optional
	Version string `json:"version,omitempty"`

	// UID of the referenced EngramTemplate for drift detection.
	// +kubebuilder:validation:Optional
	UID *types.UID `json:"uid,omitempty"`
}

type GrantCheck struct {
	FromGroup     string
	FromKind      string
	FromNamespace string

	ToGroup     string
	ToKind      string
	ToNamespace string
	ToName      string
}

type ImpulseReference struct {
	ObjectReference `json:",inline"`
	// Version pins the reference to a specific Impulse version.
	// +kubebuilder:validation:MaxLength=64
	// +optional
	Version string     `json:"version,omitempty"`
	UID     *types.UID `json:"uid,omitempty"`
}

type ImpulseTemplateReference struct {
	// Name of the referenced ImpulseTemplate.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name"`

	// Version pins the reference to a specific ImpulseTemplate version.
	// +kubebuilder:validation:MaxLength=64
	// +optional
	Version string `json:"version,omitempty"`

	// UID of the referenced ImpulseTemplate for drift detection.
	// +kubebuilder:validation:Optional
	UID *types.UID `json:"uid,omitempty"`
}

type NamespacedReferencer interface {
	ToNamespacedName(client.Object) types.NamespacedName
}

type NamespacedRuntimeObject interface {
	client.Object
	runtime.Object
}

type ObjectReference struct {
	// Name of the referenced object.
	// Must be a valid DNS-1123 label as defined by Kubernetes naming conventions.
	//
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
	Name string `json:"name"`

	// Namespace of the referenced object.
	// If empty, defaults to same namespace as the referencing object.
	//
	// Cross-namespace references should be used carefully and only when
	// multi-tenancy is properly configured. Consider the security implications:
	// - Ensure RBAC policies allow cross-namespace access
	// - Validate that the target namespace is trusted
	// - Monitor cross-namespace references for security compliance
	//
	// Note: cross-namespace references are currently rejected by admission
	// validation in the operator.
	//
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
	Namespace *string `json:"namespace,omitempty"`
}

type StepRunReference struct {
	ObjectReference `json:",inline"`

	// UID of the referenced StepRun for drift detection.
	// This field may be populated by clients or controllers to ensure the
	// reference still points at the same StepRun instance after deletion
	// and recreation.
	//
	// +kubebuilder:validation:Optional
	UID *types.UID `json:"uid,omitempty"`
}

type StoryReference struct {
	ObjectReference `json:",inline"`

	// Version pins the reference to a specific Story version.
	// +kubebuilder:validation:MaxLength=64
	// +optional
	Version string `json:"version,omitempty"`

	// UID of the referenced Story for drift detection.
	// This field is populated by controllers and should not be set by users.
	//
	// When a controller resolves this reference, it stores the target's UID.
	// On subsequent reconciliations, if the UID has changed, it indicates
	// the target was deleted and recreated, which may require special handling.
	//
	// +kubebuilder:validation:Optional
	UID *types.UID `json:"uid,omitempty"`
}

type StoryRunReference struct {
	ObjectReference `json:",inline"`

	// UID of the referenced StoryRun for drift detection.
	// This field is populated by controllers and should not be set by users.
	//
	// StoryRun drift detection helps maintain execution integrity and
	// enables proper cleanup of orphaned StepRuns.
	//
	// +kubebuilder:validation:Optional
	UID *types.UID `json:"uid,omitempty"`
}

type TemplateReference struct {
	// Name of the referenced template.
	// Templates are cluster-scoped so no namespace is needed.
	//
	// Template names should be globally unique within the cluster and
	// follow semantic versioning or other naming conventions to enable
	// upgrades and compatibility management.
	//
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
	Name string `json:"name"`

	// UID of the referenced template for drift detection.
	// This field is populated by controllers and should not be set by users.
	//
	// Template drift detection is particularly important because templates
	// define the ABI and behavior expectations for dependent resources.
	//
	// +kubebuilder:validation:Optional
	UID *types.UID `json:"uid,omitempty"`
}