v1alpha1

type EmbeddedSandboxTemplate struct {
	// Template defines the Pod template. ALL Pods in this Pool share the same
	// resources (requests/limits). The image specified here is used as the IDLE image
	// unless IdleImage is explicitly set.
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Schemaless
	// +optional
	Template corev1.PodTemplateSpec `json:"template,omitempty"`

	// IdleImage is the image to use when Pods are in the idle state.
	// If not specified, the image from Template.Spec.Containers[0].Image will be used.
	// +optional
	IdleImage string `json:"idleImage,omitempty"`

	// Runtimes specifies the runtimes to use for the sandbox pods. Each runtime has a type and optional configuration.
	// If not specified, a default runtime will be used.
	// +listType=map
	// +listMapKey=name
	// +optional
	Runtimes []SandboxRuntimeSpec `json:"runtimes,omitempty"`
}

type EnvAutoscalingGroup struct {
	// Name matches EnvClusterMember.ScalingGroup. Required. The Env
	// rejects groups whose Name does not match the ScalingGroup of at
	// least one member — empty-group policies have no effect and would
	// confuse the autoscaler's per-group iteration.
	// +required
	Name string `json:"name"`

	// Enabled toggles the autoscaler on/off for this group. When false,
	// member Pool replicas in this scaling group are managed manually.
	// +optional
	// +kubebuilder:default=false
	Enabled bool `json:"enabled,omitempty"`

	// MinReplicas is the lower bound for the aggregate (group) replica
	// count. Defaults to 0 — set explicitly so kubectl get sbe surfaces
	// the floor instead of leaving it implicit.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=0
	MinReplicas *int32 `json:"minReplicas,omitempty"`

	// MaxReplicas is the upper bound for the aggregate (group) replica
	// count. When unset, the group has NO ceiling and grows until each
	// member's own MaxReplicas, the cluster's capacity, or external
	// quotas stop it. Aggressive scaleUpPolicy.mode REQUIRES this field
	// to be set (validated via CEL) because doubling each cooldown
	// without an upper bound is unsafe.
	// +optional
	// +kubebuilder:validation:Minimum=0
	MaxReplicas *int32 `json:"maxReplicas,omitempty"`

	// ScaleUpPolicy controls how scale-up decisions are evaluated. The
	// API server fills every field with its declared default when the
	// caller omits it, so the persisted CR always carries an explicit,
	// inspectable value (no hidden code defaults).
	// +optional
	// +kubebuilder:default={}
	ScaleUpPolicy PoolScaleUpPolicy `json:"scaleUpPolicy"`

	// ScaleDownPolicy controls how scale-down decisions are evaluated.
	// Same defaulting contract as ScaleUpPolicy.
	// +optional
	// +kubebuilder:default={}
	ScaleDownPolicy PoolScaleDownPolicy `json:"scaleDownPolicy"`
}

type EnvAutoscalingSpec struct {
	// Groups is the list of autoscaling groups. Each group is keyed by Name
	// and toggles its own Enabled bit independently.
	// +optional
	// +listType=map
	// +listMapKey=name
	Groups []EnvAutoscalingGroup `json:"groups,omitempty"`
}

type EnvClusterMember struct {
	// Name is the SandboxPool's metadata.name within the Env's namespace.
	// Acts as the list map key for Members. Must equal Metadata.Name once
	// the Reconciler materialises the Pool; the Reconciler overwrites
	// Metadata.Name with Name at stamp time if they disagree.
	// +required
	Name string `json:"name"`

	// Metadata is the snapshot of the candidate Pool's mutable ObjectMeta
	// subset (Labels + Annotations) after PreCreatePool. The Reconciler
	// propagates these onto the live Pool when materialising it.
	//
	// Finalizers are intentionally NOT stored here — `SandboxPoolReconciler`
	// owns the Pool's finalizer lifecycle. Name/Namespace/UID/etc. are server
	// or Env-owned and don't belong on a per-member snapshot. Using a
	// dedicated struct (instead of metav1.ObjectMeta) avoids controller-gen
	// emitting a degenerate `type: object` schema, which K8s API server would
	// otherwise prune in admission.
	// +optional
	Metadata MemberMetadata `json:"metadata,omitempty"`

	// Spec is the snapshot of the candidate SandboxPoolSpec after
	// PreCreatePool. The Reconciler stamps the whole Spec verbatim when
	// creating the live Pool and uses equality.Semantic.DeepEqual to
	// detect drift between Spec and the live Pool on subsequent
	// reconciles, including Spec.Replicas. The Env Reconciler is the
	// sole writer of the live Pool's Replicas — both the API
	// (UpdateMember) and the Env autoscaler express their intent by
	// patching Member.Spec.Replicas here and let the Reconciler
	// propagate it.
	// +optional
	Spec SandboxPoolSpec `json:"spec,omitempty"`

	// Config carries user-declared intent: sizing (InstanceType/Multiplier
	// or InlineResources), autoscaling bookkeeping (ScalingGroup,
	// MaxReplicas), and routing priorities. Plugins do not mutate Config,
	// so it remains a faithful description of the caller's request.
	// +optional
	Config EnvClusterMemberConfig `json:"config,omitempty"`
}

type EnvClusterMemberConfig struct {
	// Labels are caller-supplied SandboxPool metadata.labels stamped onto
	// the rendered candidate Pool BEFORE PreCreatePool runs. Plugins
	// typically consume these for routing decisions (e.g. the
	// "quota.scitix.ai/url" label selects which ScitixQuota CR backs the
	// member). The plugin output — original + any plugin-added labels —
	// lands in Member.Metadata.Labels; Config.Labels stays equal to the
	// caller's input.
	// +optional
	Labels map[string]string `json:"labels,omitempty"`

	// Annotations are caller-supplied SandboxPool metadata.annotations,
	// same propagation rules as Labels.
	// +optional
	Annotations map[string]string `json:"annotations,omitempty"`

	// InstanceType references an entry in the cluster-wide InstanceType
	// catalog. Mutually informative with InlineResources: if both are set,
	// InstanceType wins and InlineResources serves as a transitional
	// record for migration.
	// +optional
	InstanceType string `json:"instanceType,omitempty"`

	// Multiplier scales InstanceType's resources. Required when
	// InstanceType is set.
	// +optional
	// +kubebuilder:validation:Minimum=0
	Multiplier int32 `json:"multiplier,omitempty"`

	// InlineResources is the Phase 1 migration escape hatch (legacy Pools
	// without an InstanceType label) AND the source of truth used by a
	// future RefreshMember API to keep resource sizing stable when the
	// underlying Template is upgraded. New Envs created via the Dashboard
	// should leave this empty and use InstanceType+Multiplier instead.
	// +optional
	InlineResources *corev1.ResourceRequirements `json:"inlineResources,omitempty"`

	// ScalingGroup names the autoscaling group this member belongs to.
	// Members in the same group must share the same effective resources
	// (= InstanceType × Multiplier or identical InlineResources). Empty
	// means the member is excluded from autoscaling.
	// +optional
	// +kubebuilder:default=default
	ScalingGroup string `json:"scalingGroup,omitempty"`

	// MinReplicas is the lower bound on this member's spec.replicas.
	// Enforced by the Env autoscaler: scale-down never shrinks this member
	// below MinReplicas. nil/0 means no per-member floor (only the group's
	// aggregate MinReplicas applies).
	// +optional
	// +kubebuilder:validation:Minimum=0
	MinReplicas *int32 `json:"minReplicas,omitempty"`

	// MaxReplicas is the upper bound on this member's spec.replicas.
	// Enforced by the Env autoscaler when distributing scale-up delta
	// across members.
	// +optional
	// +kubebuilder:validation:Minimum=0
	MaxReplicas *int32 `json:"maxReplicas,omitempty"`

	// Priority is the canonical routing/scaling preference: lower wins.
	// Also acts as the default for ScaleUpPriority / ScaleDownPriority
	// when those are unset.
	// +optional
	Priority int32 `json:"priority,omitempty"`

	// ScaleUpPriority overrides Priority for scale-up ordering within a
	// scalingGroup. Same-value tiebreak: (clusterID, name) lexicographic.
	// When nil, EffectiveScaleUpPriority falls back to Priority.
	// Reserved for Phase 2; Phase 1 ignores it.
	// +optional
	ScaleUpPriority *int32 `json:"scaleUpPriority,omitempty"`

	// ScaleDownPriority overrides Priority for scale-down ordering: lower
	// values are retained, higher values shrink first. The value direction
	// is intentionally inverted from ScaleUpPriority so that a single
	// Priority value (lower wins) means "preferred member" in both
	// directions — preferred members scale up first AND scale down last.
	// Same-value tiebreak: oldest idle Pod first, then name lexicographic.
	// When nil, EffectiveScaleDownPriority falls back to Priority.
	// +optional
	ScaleDownPriority *int32 `json:"scaleDownPriority,omitempty"`
}

type EnvClusterSpec struct {
	// ClusterID identifies the cluster that owns this segment. Each Worker
	// only mutates the segment matching its own ClusterID.
	// +required
	ClusterID string `json:"clusterID"`

	// Members is the list of SandboxPool members contributed by this cluster.
	// Phase 1 supports exactly one member per cluster.
	// +optional
	// +listType=map
	// +listMapKey=name
	Members []EnvClusterMember `json:"members,omitempty"`
}

type EnvClusterStatus struct {
	// ClusterID matches the spec's ClusterID for the same segment.
	// +required
	ClusterID string `json:"clusterID"`

	// IsLocal is true on the Worker that owns this cluster's Pools. Used to
	// gate writes: only IsLocal=true segments are mutated by the local Env
	// Reconciler.
	// +optional
	IsLocal bool `json:"isLocal,omitempty"`

	// ObservedMembers reports per-member runtime state (idle/running/desired,
	// effective resources, member state).
	// +optional
	// +listType=map
	// +listMapKey=name
	ObservedMembers []EnvObservedMember `json:"observedMembers,omitempty"`

	// LastSnapshotTime records when this segment was last updated. For
	// IsLocal=true: write time by the local Reconciler. For IsLocal=false:
	// arrival time of the Hub Sync push.
	// +optional
	LastSnapshotTime *metav1.Time `json:"lastSnapshotTime,omitempty"`
}

type EnvObservedMember struct {
	// Name matches the spec member's Name and is the list map key.
	// +required
	Name string `json:"name"`

	// InstanceType / Multiplier are echoed from spec for convenience.
	// +optional
	InstanceType string `json:"instanceType,omitempty"`
	// +optional
	Multiplier int32 `json:"multiplier,omitempty"`

	// EffectiveResources is the resolved resource request/limit per Pod
	// (= InstanceType.resources × Multiplier, or InlineResources verbatim).
	// +optional
	EffectiveResources *corev1.ResourceRequirements `json:"effectiveResources,omitempty"`

	// State summarises whether the member can currently serve requests.
	// +optional
	State ObservedMemberState `json:"state,omitempty"`

	// IdleCount, RunningCount are mirrored from SandboxPool.status to surface
	// a single Env-level view to the Dashboard.
	// +optional
	IdleCount int32 `json:"idleCount,omitempty"`
	// +optional
	RunningCount int32 `json:"runningCount,omitempty"`

	// DesiredReplicas is the most recent value the Env autoscaler patched onto
	// the member Pool's spec.replicas.
	// +optional
	DesiredReplicas int32 `json:"desiredReplicas,omitempty"`

	// CurrentReplicas is the value last observed on the Pool spec.
	// +optional
	CurrentReplicas int32 `json:"currentReplicas,omitempty"`

	// PendingRequests is the throttled mirror of the in-process PoolScheduler
	// claim queue length, copied from SandboxPool.Status.PendingRequests.
	// Used by Dashboard observability and (future) cross-cluster routing.
	// +optional
	PendingRequests int32 `json:"pendingRequests,omitempty"`

	// SaturatedUntil marks this member as ineligible for routing/scaling
	// until the given time. Read-only mirror of
	// SandboxPool.Status.AutoScaling.SaturatedUntil, refreshed by the Env
	// reconciler's status aggregation; the source of truth is the per-Pool
	// autoscaler. The router (EnvScheduler) holds saturated members back
	// from the primary candidate list but still tries them as fallback
	// when no fresh member can accept the request.
	// +optional
	SaturatedUntil *metav1.Time `json:"saturatedUntil,omitempty"`
}

type EnvOverridesSpec struct {
	// Image overrides the main container (containers[0]) image of the
	// rendered Template. Applied before any per-Member overrides.
	// +optional
	Image string `json:"image,omitempty"`

	// PodCreationImagePolicy overrides the Template's
	// spec.podCreationImagePolicy. Applied to every member Pool.
	// +optional
	// +kubebuilder:validation:Enum=PoolDefaultImage;IdleImage
	PodCreationImagePolicy PodCreationImagePolicy `json:"podCreationImagePolicy,omitempty"`

	// DefaultStartupTimeout overrides the Template's
	// spec.defaultStartupTimeout. Applied to Sandbox.Create requests that
	// don't carry an explicit startupTimeout.
	// +optional
	DefaultStartupTimeout *metav1.Duration `json:"defaultStartupTimeout,omitempty"`

	// DefaultIdleTimeout overrides the Template's spec.defaultIdleTimeout.
	// Applied to Sandboxes that don't carry an explicit idleTimeout.
	// +optional
	DefaultIdleTimeout *metav1.Duration `json:"defaultIdleTimeout,omitempty"`
}

type EnvScalingGroupStatus struct {
	// Name matches the autoscaling group's Name and is the list map key.
	// +required
	Name string `json:"name"`

	// TotalIdle / TotalRunning / TotalDesired aggregate across members.
	// +optional
	TotalIdle int32 `json:"totalIdle,omitempty"`
	// +optional
	TotalRunning int32 `json:"totalRunning,omitempty"`
	// +optional
	TotalDesired int32 `json:"totalDesired,omitempty"`
}

type MemberMetadata struct {
	// Labels are the candidate Pool's metadata.labels post-PreCreatePool.
	// +optional
	Labels map[string]string `json:"labels,omitempty"`

	// Annotations are the candidate Pool's metadata.annotations post-PreCreatePool.
	// +optional
	Annotations map[string]string `json:"annotations,omitempty"`
}

type ObservedMemberState string

type PodCreationImagePolicy string

type PoolAutoScalingStatus struct {
	// LastScaleUpTime is the wall-clock time of the most recent
	// scale-up that actually increased spec.replicas (the probe
	// accepted at least one additional replica). Drives the success
	// cooldown gate (scaleUpPolicy.cooldownSeconds).
	// +optional
	LastScaleUpTime *metav1.Time `json:"lastScaleUpTime,omitempty"`

	// LastScaleDownTime is the wall-clock time of the most recent
	// successful scale-down (spec.replicas decreased) on this Pool. Drives
	// scaleDownPolicy.stabilizationSeconds.
	// +optional
	LastScaleDownTime *metav1.Time `json:"lastScaleDownTime,omitempty"`

	// IdleZeroSince is the wall-clock time at which this Pool's idle
	// replica count first dropped to zero in the current continuous-zero
	// window. Cleared the instant idle > 0 is observed. Drives the
	// proactive scaleUpPolicy.idleThresholdSeconds trigger.
	// +optional
	IdleZeroSince *metav1.Time `json:"idleZeroSince,omitempty"`

	// LastScaleUpAttemptTime records when the autoscaler last invoked
	// the admission probe for a scale-up, regardless of whether the
	// probe accepted the target. Together with LastScaleUpAttemptResult
	// and the group's SaturationCooldownSeconds it drives the saturation
	// cooldown: when the last attempt was Insufficient / JustRight /
	// Failed, the autoscaler and router treat the Pool as saturated
	// until SaturationCooldownSeconds has elapsed past this timestamp.
	// +optional
	LastScaleUpAttemptTime *metav1.Time `json:"lastScaleUpAttemptTime,omitempty"`

	// LastScaleUpAttemptResult records the outcome of the most recent
	// scale-up admission probe. Empty before the first attempt; one of
	// the PoolScaleUpAttemptResult enum values otherwise.
	// +optional
	LastScaleUpAttemptResult PoolScaleUpAttemptResult `json:"lastScaleUpAttemptResult,omitempty"`

	// ScaleUpErrorMessage is a short single-line description of the most
	// recent non-Enough scale-up result, suitable for surfacing to the
	// dashboard. Empty when LastScaleUpAttemptResult is Enough.
	// +optional
	ScaleUpErrorMessage string `json:"scaleUpErrorMessage,omitempty"`

	// ObservedGeneration is the metadata.generation observed when the
	// autoscaler last wrote this block. Clients may use it to confirm the
	// status is current with respect to the spec they care about.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
}

type PoolScaleDownPolicy struct {
	// IdleTimeoutSeconds is the minimum duration (in seconds) a Pod must remain
	// in Idle state before it becomes a candidate for scale-down.
	// Defaults to 300 (5 minutes).
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=300
	IdleTimeoutSeconds int32 `json:"idleTimeoutSeconds,omitempty"`

	// StabilizationSeconds is the minimum number of seconds between two consecutive
	// scale-down events. Prevents thrashing when load fluctuates around the threshold.
	// Defaults to 60.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=60
	StabilizationSeconds int32 `json:"stabilizationSeconds,omitempty"`

	// ProtectionWindowSeconds is the time window after a Pod is marked for
	// scale-down (via the scale-down-protected annotation) during which a new
	// Create Sandbox request can still claim it, cancelling the scale-down intent.
	// Defaults to 10.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=10
	ProtectionWindowSeconds int32 `json:"protectionWindowSeconds,omitempty"`
}

type PoolScaleUpAttemptResult string

type PoolScaleUpMode string

type PoolScaleUpPolicy struct {
	// Mode controls how aggressively the pool grows on each scale-up decision.
	//   - Conservative: +1 per decision
	//   - Default:      +max(1, ceil(currentReplicas/2))
	//   - Aggressive:   scale to min(currentReplicas*2, maxReplicas)
	// Defaults to Default.
	// +optional
	// +kubebuilder:validation:Enum=Conservative;Default;Aggressive
	// +kubebuilder:default=Default
	Mode PoolScaleUpMode `json:"mode,omitempty"`

	// CooldownSeconds is the minimum number of seconds between two consecutive
	// scale-up events. Prevents scale-up storms when many requests arrive simultaneously.
	// Defaults to 30.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=30
	CooldownSeconds int32 `json:"cooldownSeconds,omitempty"`

	// IdleThresholdSeconds triggers a proactive scale-up when idleReplicas == 0
	// has persisted for this many seconds. Set to 0 to disable proactive scale-up.
	// Defaults to 30.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=30
	IdleThresholdSeconds int32 `json:"idleThresholdSeconds,omitempty"`

	// IdleZeroQuietWindowSeconds suppresses the proactive idleZero
	// scale-up trigger when no Sandbox.Create request has been observed
	// for this Pool within the most recent window. Concretely: if
	// `now - LastSandboxCreateTime > idleZeroQuietWindowSeconds` AND
	// `IdleThresholdSeconds` has elapsed since `idleReplicas` last hit
	// zero, the autoscaler will NOT fire a proactive scale-up. Reactive
	// scale-ups (queue length > 0 with no idle Pod) ignore this window
	// — a real waiter always wins. Set to 0 to disable the quiet-window
	// gate so proactive scale-up fires the moment IdleThresholdSeconds
	// elapses.
	// Defaults to 300 (5 minutes).
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=300
	IdleZeroQuietWindowSeconds int32 `json:"idleZeroQuietWindowSeconds,omitempty"`

	// SaturationCooldownSeconds is the duration the Env autoscaler keeps
	// a member marked saturated after a probe returned InsufficientResources
	// (or InvalidSpec). Subsequent reconciles skip the member's expensive
	// PreUpdatePool probe until the cooldown elapses; the router also
	// deprioritises saturated members. Defaults to 60.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=60
	SaturationCooldownSeconds int32 `json:"saturationCooldownSeconds,omitempty"`
}

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

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec defines the desired state of SandboxEnv
	// +required
	Spec SandboxEnvSpec `json:"spec"`

	// status defines the observed state of SandboxEnv
	// +optional
	Status SandboxEnvStatus `json:"status,omitzero"`
}

type SandboxEnvDefaults struct {
	// InstanceType references an entry in the cluster-wide InstanceType catalog.
	// May be empty when the Env was migrated from a legacy SandboxPool that did
	// not carry an InstanceType label — in that case members use InlineResources.
	// +optional
	InstanceType string `json:"instanceType,omitempty"`

	// Multiplier scales the InstanceType's base resources. Must fall within the
	// InstanceType's declared [min, max] range; validated by the Env Controller.
	// +optional
	// +kubebuilder:validation:Minimum=1
	Multiplier int32 `json:"multiplier,omitempty"`
}

type SandboxEnvList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []SandboxEnv `json:"items"`
}

type SandboxEnvMode string

type SandboxEnvSpec struct {
	// TemplateRef binds this Env to exactly one SandboxTemplate (runtime). All
	// member Pools must reference the same Template.
	// +required
	TemplateRef SandboxEnvTemplateRef `json:"templateRef"`

	// Mode selects between WarmPool (predefined member Pools) and OnDemandJob
	// (per-request SandboxJob).
	// +required
	// +kubebuilder:default=WarmPool
	Mode SandboxEnvMode `json:"mode"`

	// Defaults supplies the InstanceType and multiplier used when a Sandbox.create
	// request does not specify them explicitly. Strongly recommended.
	// +optional
	Defaults *SandboxEnvDefaults `json:"defaults,omitempty"`

	// Clusters is the per-cluster member list. Each segment is owned exclusively
	// by the Worker whose ClusterID matches; foreign segments are read-only to
	// other Workers. Hub merges contributions from all Workers in Phase 2.
	// +optional
	// +listType=map
	// +listMapKey=clusterID
	Clusters []EnvClusterSpec `json:"clusters,omitempty"`

	// Autoscaling configures the Env-level autoscaler. When nil or
	// Autoscaling.Enabled=false, member Pool replicas are managed manually.
	// +optional
	Autoscaling *EnvAutoscalingSpec `json:"autoscaling,omitempty"`

	// Overrides carries the Env-wide overrides that uniformly replace
	// fields of the referenced SandboxTemplate for every member Pool.
	// Per-Pool variations (resource multiplier, replicas, plugin metadata
	// like quota URLs) live on each EnvClusterMember instead.
	// +optional
	Overrides *EnvOverridesSpec `json:"overrides,omitempty"`
}

type SandboxEnvStatus struct {
	// Conditions surfaces high-level Env health signals (Ready,
	// TemplateConsistent, AutoscalingActive, …).
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Clusters carries the per-cluster observed state. Worker writes only the
	// segment with IsLocal=true; other segments are populated by Hub Sync.
	// +optional
	// +listType=map
	// +listMapKey=clusterID
	Clusters []EnvClusterStatus `json:"clusters,omitempty"`

	// ScalingGroups aggregates idle/running counts per scalingGroup across all
	// members (across clusters when remote segments are populated by Sync).
	// +optional
	// +listType=map
	// +listMapKey=name
	ScalingGroups []EnvScalingGroupStatus `json:"scalingGroups,omitempty"`

	// MemberCount is the total number of member Pools, summed across every
	// cluster segment. It exists because printer columns cannot evaluate the
	// nested clusters[].members[] array. Today only the local segment is
	// observed, so it equals the local member count; once foreign segments are
	// populated it reflects the cross-cluster total.
	// +optional
	MemberCount int32 `json:"memberCount,omitempty"`

	// DesiredReplicas, RunningReplicas, IdleReplicas are env-wide rollups of
	// the per-member counts, summed across every observed member. They back
	// the printer columns (which cannot sum nested arrays) and give a single
	// at-a-glance view of capacity vs. utilisation.
	// +optional
	DesiredReplicas int32 `json:"desiredReplicas,omitempty"`
	// +optional
	RunningReplicas int32 `json:"runningReplicas,omitempty"`
	// +optional
	IdleReplicas int32 `json:"idleReplicas,omitempty"`
}

type SandboxEnvTemplateRef struct {
	// Name of the SandboxTemplate (cluster-scoped).
	// +required
	Name string `json:"name"`

	// Version optionally pins the Env to a specific Template version. When
	// empty, the Template's current spec.version is observed and recorded in
	// status.
	// +optional
	Version string `json:"version,omitempty"`
}

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

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec defines the desired state of SandboxPool
	// +required
	Spec SandboxPoolSpec `json:"spec"`

	// status defines the observed state of SandboxPool
	// +optional
	Status SandboxPoolStatus `json:"status,omitzero"`
}

type SandboxPoolList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []SandboxPool `json:"items"`
}

type SandboxPoolPhase string

type SandboxPoolSpec struct {

	// Replicas is the total desired number of Pods (Idle + Running + Starting + Stopping).
	// Adjusted by the SandboxEnv autoscaler (when the Pool is owned by an Env) or
	// directly by the operator for unmanaged Pools.
	// +kubebuilder:validation:Minimum=0
	Replicas int32 `json:"replicas"`

	// TemplateName references a cluster-scoped SandboxTemplate to use as the base
	// configuration. When set, the template's EmbeddedSandboxTemplate is copied at
	// creation time. Inline fields in SandboxPoolSpec override template fields.
	// +optional
	TemplateName string `json:"templateName,omitempty"`

	// DefaultStartupTimeout is the default startup timeout applied to sandbox create
	// requests in this pool when the CreateSandbox request does not specify a startupTimeout.
	// It also serves as the upper bound for the Starting phase: the controller deletes any pod
	// that has been in Starting phase longer than this value.
	//
	// When nil, the controller does not enforce an upper bound on the Starting phase
	// (pods with a per-pod agentbox.navix.sh/startup-timeout annotation are still cleaned up),
	// and create requests without an explicit startupTimeout use the internal default (2 minutes).
	// +optional
	DefaultStartupTimeout *metav1.Duration `json:"defaultStartupTimeout,omitempty"`

	// DefaultIdleTimeout is the default idle timeout applied to sandboxes created
	// in this pool when the CreateSandbox request does not specify an idleTimeout.
	// If nil, sandboxes have no idle timeout by default (they run until explicitly released).
	// +optional
	DefaultIdleTimeout *metav1.Duration `json:"defaultIdleTimeout,omitempty"`

	// PodCreationImagePolicy controls which image newly created Pods start with,
	// regardless of whether replicas are increased manually or by autoscaling.
	//   - PoolDefaultImage: preserve template container image (current behavior)
	//   - IdleImage:        override the first container image with spec.idleImage
	// +optional
	// +kubebuilder:validation:Enum=PoolDefaultImage;IdleImage
	// +kubebuilder:default=IdleImage
	PodCreationImagePolicy PodCreationImagePolicy `json:"podCreationImagePolicy,omitempty"`

	EmbeddedSandboxTemplate `json:",inline"`
}

type SandboxPoolStatus struct {

	// Phase is a high-level summary of the pool's current state.
	// Possible values: Pending, Ready, ScalingUp, ScalingDown, Degraded, Terminating.
	//
	// Phase is determined by the following priority rules:
	//   - Terminating: DeletionTimestamp is set
	//   - Pending:     spec.replicas == 0 and no pods exist
	//   - ScalingUp:   current pod count < spec.replicas
	//   - ScalingDown: current pod count > spec.replicas (may persist while running pods cannot be deleted)
	//   - Degraded:    replica count is stable but unavailableIdleReplicas > 0 or failedReplicas > 0
	//   - Ready:       all replicas present and all pods are healthy
	// +optional
	Phase SandboxPoolPhase `json:"phase,omitempty"`

	// IdleReplicas is the number of Pods in idle state
	// +optional
	IdleReplicas int32 `json:"idleReplicas,omitempty"`

	// UnavailableIdleReplicas is the number of Pods in idle phase whose Kubernetes PodReady
	// condition is not True (e.g. Pending, CrashLoopBackOff, ErrImagePull).
	// These Pods are counted in IdleReplicas but cannot accept sandbox requests.
	// A non-zero value causes the pool to enter the Degraded phase.
	// +optional
	UnavailableIdleReplicas int32 `json:"unavailableIdleReplicas,omitempty"`

	// RunningReplicas is the number of Pods in running state
	// +optional
	RunningReplicas int32 `json:"runningReplicas,omitempty"`

	// StartingReplicas is the number of Pods being activated (Idle → Running)
	// +optional
	StartingReplicas int32 `json:"startingReplicas,omitempty"`

	// StoppingReplicas is the number of Pods being recycled (Running → Idle)
	// +optional
	StoppingReplicas int32 `json:"stoppingReplicas,omitempty"`

	// FailedReplicas is the number of Pods in failed state
	// +optional
	FailedReplicas int32 `json:"failedReplicas,omitempty"`

	// PendingRequests is the throttled mirror of the in-process PoolScheduler
	// claim queue depth. Patched every ~3 s when the queue length changes by
	// at least 20 % or crosses the 0/>0 boundary. Used by Dashboard for
	// real-time backlog observability; the Env autoscaler reads the live
	// in-process Snapshot instead and does not depend on this field.
	// +optional
	PendingRequests int32 `json:"pendingRequests,omitempty"`

	// Selector is the label selector string used to identify Pods managed by this Pool.
	// Deprecated: Use LabelSelector for structured access or PhaseSelectors for per-phase filtering.
	// This field is retained for kubectl scale / HPA compatibility (subresource:scale selectorpath).
	// +optional
	Selector string `json:"selector,omitempty"`

	// LabelSelector is the structured label selector matching all Pods managed by this Pool.
	// Equivalent to the Selector field but in structured metav1.LabelSelector form.
	// +optional
	LabelSelector *metav1.LabelSelector `json:"labelSelector,omitempty"`

	// PhaseSelectors contains pre-computed label selector strings for filtering Pods by phase,
	// suitable for direct use with `kubectl get pods -l <selector>`.
	// Keys: "all", "idle", "running", "starting", "stopping", "failed".
	// Example: kubectl get pods -l <phaseSelectors.running>
	// +optional
	PhaseSelectors map[string]string `json:"phaseSelectors,omitempty"`

	// conditions represent the current state of the SandboxPool resource.
	// Each condition has a unique type and reflects the status of a specific aspect of the resource.
	//
	// Standard condition types:
	// - "Available":  True when healthy idle pods are available to accept new sandbox requests.
	// - "Scaling":    True when the pool is actively scaling up or down.
	// - "Degraded":   True when unavailable idle pods or failed pods are present.
	//
	// The status of each condition is one of True, False, or Unknown.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// AutoScaling persists the Pool autoscaler's decision-time bookkeeping
	// (last scale-up/down timestamps, idle-zero window start, saturation
	// cooldown, last probe outcome). The Pool reconciler is the only writer.
	// Nil when autoscaling is disabled on this Pool's owning Env group.
	// +optional
	AutoScaling *PoolAutoScalingStatus `json:"autoscaling,omitempty"`
}

type SandboxReservationSpec struct {
	PriorityClassName string              `json:"priorityClassName,omitempty"`
	ReplicaQuota      corev1.ResourceList `json:"replicaQuota"`
}

type SandboxRuntimeSpec struct {
	// Name specifies the name of the runtime to use for the sandbox pods.
	// Supported values are "e2b", "swerex", "aiosanbdox", etc.
	Name string `json:"name"`

	// Port specifies the port number that the runtime should listen on for incoming connections.
	// +optional
	Port *int32 `json:"port,omitempty"`

	// Protocol for port. Must be UDP, TCP, or SCTP.
	// Defaults to "TCP".
	// +optional
	// +default="TCP"
	Protocol *corev1.Protocol `json:"protocol,omitempty"`

	// Description is a human-readable description of this runtime.
	// +optional
	Description string `json:"description,omitempty"`

	// LogDir is the path to the runtime's log file inside the container.
	// When set, the GetLogs API can retrieve runtime logs via file read.
	// Example: "/tmp/envd.log"
	// +optional
	LogDir string `json:"logDir,omitempty"`

	// ReadinessProbe defines the readiness check configuration for the runtime.
	// +optional
	ReadinessProbe *corev1.Probe `json:"readinessProbe,omitempty"`

	// Config contains runtime-specific configuration parameters.
	// The content and structure of this field depend on the runtime type.
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Schemaless
	// +optional
	Config *runtime.RawExtension `json:"config,omitempty"`
}

type SandboxStatusDetail struct {
	// Reason is a machine-readable cause, e.g. "Pulling", "ImagePullBackOff",
	// "ErrImagePull", "CrashLoopBackOff", "OOMKilled", "PodFailed".
	Reason string `json:"reason"`
	// Message is a human-readable description of the current state.
	Message string `json:"message"`
	// LastUpdatedTime is the RFC3339 timestamp when this record was last written.
	LastUpdatedTime string `json:"lastUpdatedTime"`
}

type SandboxStopReason string

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

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec defines the desired state of SandboxTemplate
	// +required
	Spec SandboxTemplateSpec `json:"spec"`

	// status defines the observed state of SandboxTemplate
	// +optional
	Status SandboxTemplateStatus `json:"status,omitzero"`
}

type SandboxTemplateList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []SandboxTemplate `json:"items"`
}

type SandboxTemplateSpec struct {
	EmbeddedSandboxTemplate `json:",inline"`

	// Version is an optional semantic version string for this template (e.g. "v1.2.0").
	// +optional
	Version string `json:"version,omitempty"`

	// Description is a human-readable description of this template.
	// +optional
	Description string `json:"description,omitempty"`

	// Visibility controls which tenants can see this template.
	// When nil or Rules is empty, the template is public (visible to all).
	// +optional
	Visibility *TemplateVisibility `json:"visibility,omitempty"`
}

type SandboxTemplateStatus struct {

	// conditions represent the current state of the SandboxTemplate resource.
	// Each condition has a unique type and reflects the status of a specific aspect of the resource.
	//
	// Standard condition types include:
	// - "Available": the resource is fully functional
	// - "Progressing": the resource is being created or updated
	// - "Degraded": the resource failed to reach or maintain its desired state
	//
	// The status of each condition is one of True, False, or Unknown.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type TemplateVisibility struct {
	// Rules is the list of visibility rules.
	// +optional
	Rules []TemplateVisibilityRule `json:"rules,omitempty"`
}

type TemplateVisibilityRule struct {
	// Team specifies the team that can see the template.
	// Empty means any team.
	// +optional
	Team string `json:"team,omitempty"`

	// Users specifies the users that can see the template.
	// Empty means any user.
	// +optional
	Users []string `json:"users,omitempty"`
}