types

type ACMEConfig struct {
	Directory string `yaml:"directory,omitempty"`
	Email     string `yaml:"email,omitempty"`
}

type AccessMode string

type AlertRule struct {
	// Unique identifier.
	ID string `json:"id" yaml:"id"`

	// DNS-1123 cluster-unique name.
	Name string `json:"name" yaml:"name"`

	// Description is optional free text shown in the rules table.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// LogQL is the log selector + line filters whose matching lines are
	// counted (e.g. `{service="payments", level="error"} |= "boom"`). It must
	// be a plain log query — the alerter adds the count_over_time aggregation
	// itself. Validated at save time.
	LogQL string `json:"logql" yaml:"logql"`

	// Window is the rolling count window (the `[5m]` part).
	Window time.Duration `json:"window" yaml:"window"`

	// Op compares the windowed count to Threshold: ">", ">=", "<", "<=",
	// "==". Absence/heartbeat alerts are `== 0` (or `< 1`).
	Op string `json:"op" yaml:"op"`

	// Threshold is the count compared against.
	Threshold float64 `json:"threshold" yaml:"threshold"`

	// For is how long the condition must hold before pending becomes firing
	// (the hysteresis that stops one noisy evaluation from paging). Zero
	// fires on the first true evaluation.
	For time.Duration `json:"for,omitempty" yaml:"for,omitempty"`

	// Interval is the evaluation cadence. Zero uses the alerter default (60s).
	Interval time.Duration `json:"interval,omitempty" yaml:"interval,omitempty"`

	// Channels are the Channel names notified on firing and resolved
	// transitions. Alert state changes always also emit a Rune event.
	Channels []string `json:"channels,omitempty" yaml:"channels,omitempty"`

	// Disabled pauses evaluation without deleting the rule. (Inverted so the
	// zero value means enabled.)
	Disabled bool `json:"disabled,omitempty" yaml:"disabled,omitempty"`

	// CreatedBy attributes the rule (auth principal name; informational).
	CreatedBy string `json:"createdBy,omitempty" yaml:"createdBy,omitempty"`

	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
}

type AuditEvent struct {
	// ID is a unique identifier for the event; ulid-or-uuid string.
	ID string `json:"id" yaml:"id"`

	// Timestamp is when the event was emitted (server clock).
	Timestamp time.Time `json:"timestamp" yaml:"timestamp"`

	// Actor is the authenticated subject ID, or "anonymous" if no auth was
	// established (e.g., bootstrap path) or "unknown" if we could not extract
	// a subject from the request context.
	Actor string `json:"actor" yaml:"actor"`

	// Action is the verb performed (create, update, delete, get, reveal, ...).
	Action string `json:"action" yaml:"action"`

	// Resource is the resource type (e.g., "secrets", "configmaps").
	Resource string `json:"resource" yaml:"resource"`

	// ResourceRef is the canonical "<namespace>/<name>" reference of the
	// affected object, when applicable. Empty for namespace-less actions.
	ResourceRef string `json:"resourceRef,omitempty" yaml:"resourceRef,omitempty"`

	// Namespace is the namespace of the resource (denormalized from ResourceRef
	// for cheap filtering).
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`

	// Outcome reports whether the operation succeeded.
	Outcome AuditOutcome `json:"outcome" yaml:"outcome"`

	// Message is an optional human-readable note (failure reason, etc.).
	// MUST NOT contain plaintext secret payloads.
	Message string `json:"message,omitempty" yaml:"message,omitempty"`

	// Metadata is a free-form bag for non-sensitive context (e.g., key set
	// hash, version number, previous version on rollback).
	Metadata map[string]string `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

type AuditOutcome string

type AuthConfig struct {
	APIKeys          string `yaml:"api_keys,omitempty"`
	Provider         string `yaml:"provider,omitempty"`
	Token            string `yaml:"token,omitempty"`
	AllowRemoteAdmin bool   `yaml:"allow_remote_admin,omitempty"`
}

type CORSPolicy struct {
	// Allowed origins (e.g., "https://example.com")
	AllowOrigins []string `json:"allowOrigins" yaml:"allowOrigins"`

	// Allowed methods (e.g., "GET", "POST")
	AllowMethods []string `json:"allowMethods,omitempty" yaml:"allowMethods,omitempty"`

	// Allowed headers
	AllowHeaders []string `json:"allowHeaders,omitempty" yaml:"allowHeaders,omitempty"`

	// Exposed headers
	ExposeHeaders []string `json:"exposeHeaders,omitempty" yaml:"exposeHeaders,omitempty"`

	// Max age for CORS preflight requests in seconds
	MaxAge int `json:"maxAge,omitempty" yaml:"maxAge,omitempty"`

	// Allow credentials
	AllowCredentials bool `json:"allowCredentials,omitempty" yaml:"allowCredentials,omitempty"`
}

type CPUConfig struct {
	DefaultRequest string `yaml:"default_request,omitempty"`
	DefaultLimit   string `yaml:"default_limit,omitempty"`
}

type CastFile struct {
	Specs          []Spec          `yaml:"specs,omitempty"`
	Services       []ServiceSpec   `yaml:"services,omitempty"`
	Secrets        []SecretSpec    `yaml:"secrets,omitempty"`
	Configmaps     []ConfigmapSpec `yaml:"configmaps,omitempty"`
	StorageClasses []StorageClass  `yaml:"storageClasses,omitempty"`
	Volumes        []Volume        `yaml:"volumes,omitempty"`
	// contains filtered or unexported fields
}

type Channel struct {
	// Unique identifier.
	ID string `json:"id" yaml:"id"`

	// DNS-1123 cluster-unique name (what rules reference).
	Name string `json:"name" yaml:"name"`

	// Type is "webhook" or "slack" (a webhook preset).
	Type string `json:"type" yaml:"type"`

	// URL is the HTTP(S) endpoint POSTed on alert transitions. May contain
	// ${secret:namespace/name/key} references resolved at send time.
	URL string `json:"url" yaml:"url"`

	// Headers are added to the request. Values may contain
	// ${secret:namespace/name/key} references (e.g. an Authorization bearer
	// token), resolved at send time — never stored resolved.
	Headers map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"`

	// Body is an optional Go text/template for the request payload. Template
	// data: {{.Rule}} {{.State}} {{.PrevState}} {{.Value}} {{.Threshold}}
	// {{.Op}} {{.Window}} {{.LogQL}} {{.Since}} {{.Description}}. Empty uses
	// the default JSON payload (or the Slack preset for type slack).
	Body string `json:"body,omitempty" yaml:"body,omitempty"`

	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
}

type ClickHouseConfig struct {
	// DSN is the connection string (clickhouse://user:pass@host:9000/db).
	DSN string `yaml:"dsn,omitempty"`
	// Database is the target database (default "runesight").
	Database string `yaml:"database,omitempty"`
	// Table is the target log table (default "logs").
	Table string `yaml:"table,omitempty"`
	// AutoMigrate creates the database/table on first connect (default true).
	AutoMigrate bool `yaml:"auto_migrate,omitempty"`
	// StoragePolicy is the server-configured policy naming the hot + s3
	// volumes. Empty disables tiering.
	StoragePolicy string `yaml:"storage_policy,omitempty"`
	// S3Volume is the volume within StoragePolicy aged parts move to
	// (default "s3").
	S3Volume string `yaml:"s3_volume,omitempty"`
	// HotDays moves parts older than this to S3Volume. 0 keeps everything
	// on the hot disk.
	HotDays int `yaml:"hot_days,omitempty"`
}

type ClientConfig struct {
	Timeout time.Duration `yaml:"timeout,omitempty"`
	Retries int           `yaml:"retries,omitempty"`
}

type Cluster struct {
	// Unique identifier for the cluster
	ID string `json:"id" yaml:"id"`

	// Human-readable name for the cluster
	Name string `json:"name" yaml:"name"`

	// Version of the cluster schema
	Version string `json:"version" yaml:"version"`

	// Nodes that are part of this cluster
	Nodes []Node `json:"nodes,omitempty" yaml:"nodes,omitempty"`

	// Services deployed in this cluster
	Services []Service `json:"services,omitempty" yaml:"services,omitempty"`

	// Creation timestamp
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`

	// Last update timestamp
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
}

type ClusterNetwork struct {
	// CIDR is the service VIP range, e.g. "10.96.0.0/16". Set once at
	// bootstrap; changing it requires a cluster reset.
	CIDR string `json:"cidr"`

	// AllocatedVIPs maps serviceID → IP (string form, e.g. "10.96.0.7").
	// Stored as strings to keep JSON / proto round-trips stable.
	AllocatedVIPs map[string]string `json:"allocatedVIPs,omitempty"`

	// FreeList is the queue of IPs available for the next allocation.
	// IPs returned by Release reach FreeList only after the cooldown
	// period elapses. Stored as strings for the same reason as above.
	FreeList []string `json:"freeList,omitempty"`
}

type ConfigResourceConfig struct {
	Limits *LimitsConfig `yaml:"limits,omitempty"`
}

type Configmap struct {
	// Unique identifier for the config
	ID string `json:"id" yaml:"id"`

	// Human-readable name for the config (DNS-1123 unique name within a namespace)
	Name string `json:"name" yaml:"name"`

	// Namespace the config belongs to
	Namespace string `json:"namespace" yaml:"namespace"`

	// Configuration data (not encrypted)
	Data map[string]string `json:"data" yaml:"data"`

	// Current version number
	Version int `json:"version" yaml:"version"`

	// Creation timestamp
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`

	// Last update timestamp
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`

	// OwnedBy is the system ownership stamp set when a runeset release manages
	// this configmap. See _docs/plugins/RUNESET_STATEFUL_RELEASES.md.
	OwnedBy *OwnedBy `json:"ownedBy,omitempty" yaml:"ownedBy,omitempty"`
}

type ConfigmapMount struct {
	// Name of the mount (for identification)
	Name string `json:"name" yaml:"name"`

	// Path where the config should be mounted
	MountPath string `json:"mountPath" yaml:"mountPath"`

	// Name of the config to mount
	ConfigmapName string `json:"configmapName" yaml:"configmapName"`

	// Optional: specific keys to project from the config
	Items []KeyToPath `json:"items,omitempty" yaml:"items,omitempty"`
}

type ConfigmapSpec struct {
	// Human-readable name for the config (required)
	Name string `json:"name" yaml:"name"`

	// Namespace the config belongs to (optional, defaults to "default")
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`

	// Config data
	Data map[string]string `json:"data" yaml:"data"`

	// Skip indicates this spec should be ignored by castfile parsing
	Skip bool `json:"skip,omitempty" yaml:"skip,omitempty"`
	// contains filtered or unexported fields
}

type DeletionOperation struct {
	// Unique identifier for the operation
	ID string `json:"id"`

	// Namespace the service belongs to
	Namespace string `json:"namespace"`

	// Name of the service being deleted
	ServiceName string `json:"service_name"`

	// Total number of instances to delete
	TotalInstances int `json:"total_instances"`

	// Number of instances deleted so far
	DeletedInstances int `json:"deleted_instances"`

	// Number of failed instance deletions
	FailedInstances int `json:"failed_instances"`

	// Time the operation started
	StartTime time.Time `json:"start_time"`

	// Time the operation ended (if completed/failed/cancelled)
	EndTime *time.Time `json:"end_time,omitempty"`

	// Current status of the operation (combines previous status and phase)
	Status DeletionOperationStatus `json:"status"`

	// Whether this is a dry run operation
	DryRun bool `json:"dry_run"`

	// Reason for failure/cancellation if applicable
	FailureReason string `json:"failure_reason,omitempty"`

	// List of pending cleanup operations
	PendingOperations []string `json:"pending_operations,omitempty"`

	// Estimated completion time
	EstimatedCompletion *time.Time `json:"estimated_completion,omitempty"`

	// Finalizers that need to complete before deletion (ordered by execution)
	Finalizers []Finalizer `json:"finalizers,omitempty"`
}

type DeletionOperationStatus string

type DeletionRequest struct {
	// Namespace of the service
	Namespace string `json:"namespace"`

	// Name of the service
	Name string `json:"name"`

	// Force deletion without confirmation
	Force bool `json:"force"`

	// Timeout for graceful shutdown
	TimeoutSeconds int32 `json:"timeout_seconds"`

	// Detach and return immediately
	Detach bool `json:"detach"`

	// Dry run mode
	DryRun bool `json:"dry_run"`

	// Grace period for graceful shutdown
	GracePeriod int32 `json:"grace_period"`

	// Immediate deletion without graceful shutdown
	Now bool `json:"now"`

	// Don't error if service doesn't exist
	IgnoreNotFound bool `json:"ignore_not_found"`

	// Optional finalizers to run
	Finalizers []string `json:"finalizers,omitempty"`
}

type DeletionResponse struct {
	// ID of the deletion operation
	DeletionID string `json:"deletion_id"`

	// Status of the deletion
	Status string `json:"status"`

	// Warning messages
	Warnings []string `json:"warnings,omitempty"`

	// Error messages
	Errors []string `json:"errors,omitempty"`

	// Whether cleanup was partial
	PartialCleanup bool `json:"partial_cleanup"`

	// Finalizers that will be executed
	Finalizers []Finalizer `json:"finalizers,omitempty"`
}

type DependencyRef struct {
	Service   string `json:"service,omitempty" yaml:"service,omitempty"`
	Secret    string `json:"secret,omitempty" yaml:"secret,omitempty"`
	Configmap string `json:"configmap,omitempty" yaml:"configmap,omitempty"`
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
}

type DockerConfig struct {
	APIVersion                string                 `yaml:"api_version,omitempty"`
	FallbackAPIVersion        string                 `yaml:"fallback_api_version,omitempty"`
	NegotiationTimeoutSeconds int                    `yaml:"negotiation_timeout_seconds,omitempty"`
	LogMaxSize                string                 `yaml:"log_max_size,omitempty"`
	LogMaxFile                int                    `yaml:"log_max_file,omitempty"`
	Registries                []DockerRegistryConfig `yaml:"registries,omitempty"`
}

type DockerRegistryAuth struct {
	Type       string            `yaml:"type,omitempty"` // basic | token | ecr
	Username   string            `yaml:"username,omitempty"`
	Password   string            `yaml:"password,omitempty"`
	Token      string            `yaml:"token,omitempty"`
	Region     string            `yaml:"region,omitempty"`
	FromSecret any               `yaml:"fromSecret,omitempty"` // string or {name,namespace}
	Bootstrap  bool              `yaml:"bootstrap,omitempty"`
	Manage     string            `yaml:"manage,omitempty"`
	Immutable  bool              `yaml:"immutable,omitempty"`
	Data       map[string]string `yaml:"data,omitempty"`
}

type DockerRegistryConfig struct {
	Name     string             `yaml:"name"`
	Registry string             `yaml:"registry"`
	Auth     DockerRegistryAuth `yaml:"auth,omitempty"`
}

type EgressRule struct {
	To    []NetworkPolicyPeer `json:"to" yaml:"to"`
	Ports []string            `json:"ports,omitempty" yaml:"ports,omitempty"`
}

type EncryptionConfig struct {
	Enabled bool       `yaml:"enabled"`
	KEK     *KEKConfig `yaml:"kek,omitempty"`
}

type Endpoint struct {
	// Instance ID this endpoint belongs to
	InstanceID string `json:"instanceId" yaml:"instanceId"`

	// IP address for this endpoint
	IP string `json:"ip" yaml:"ip"`

	// Port for this endpoint
	Port int `json:"port" yaml:"port"`

	// Protocol for this endpoint
	Protocol string `json:"protocol,omitempty" yaml:"protocol,omitempty"`

	// Endpoint-specific metadata
	Metadata map[string]string `json:"metadata,omitempty" yaml:"metadata,omitempty"`

	// Health status for this endpoint
	Healthy bool `json:"healthy" yaml:"healthy"`

	// Last health check timestamp
	LastCheck time.Time `json:"lastCheck,omitempty" yaml:"lastCheck,omitempty"`
}

type EnvFromList []EnvFromSourceSpec

type EnvFromSource struct {
	// Exactly one of these will be set
	SecretName    string `json:"secretName,omitempty" yaml:"secretName,omitempty"`
	ConfigmapName string `json:"configmapName,omitempty" yaml:"configmapName,omitempty"`

	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	Prefix    string `json:"prefix,omitempty" yaml:"prefix,omitempty"`
}

type EnvFromSourceSpec struct {
	// One of these must be set
	Secret    string `json:"secret,omitempty" yaml:"secret,omitempty"`
	Configmap string `json:"configmap,omitempty" yaml:"configmap,omitempty"`

	// Optional namespace; defaults to the service namespace
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`

	// Optional prefix to apply to each imported key
	Prefix string `json:"prefix,omitempty" yaml:"prefix,omitempty"`

	// Raw holds the original scalar form (possibly a template placeholder) used during restoration
	Raw string `json:"-" yaml:"-"`
}

type Event struct {
	// ID is the stable, per-resource identifier "<kind>/<name>/<resourceSeq>".
	// It is the idempotency key for server-side dedup at any consumer.
	ID string `json:"id" yaml:"id"`

	// Seq is a node-global monotonic sequence number. It lets an
	// external consumer track delivery progress with a single cursor
	// (see EventLog.ListSince) instead of a per-resource map.
	Seq int64 `json:"seq" yaml:"seq"`

	// Namespace / Kind / Name identify the resource the event is about.
	// Kind is "Instance" | "Service" | "Volume" | "Node".
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	Kind      string `json:"kind" yaml:"kind"`
	Name      string `json:"name" yaml:"name"`

	// UID ties the event to a specific incarnation of the resource
	// (e.g. one instance UUID), so `describe --previous` can separate
	// a dead incarnation's events from the live one's.
	UID string `json:"uid,omitempty" yaml:"uid,omitempty"`

	// Level is the event severity.
	Level EventLevel `json:"level" yaml:"level"`

	// Reason is the machine-readable slug (e.g. "VolumeNotReady").
	Reason string `json:"reason,omitempty" yaml:"reason,omitempty"`

	// Message is the human-readable sentence.
	Message string `json:"message" yaml:"message"`

	// FirstSeen / LastSeen bound the fold window: an event identical to
	// the most recent one for its resource (same Reason+Message+UID)
	// bumps LastSeen and Count instead of appending a new record.
	FirstSeen time.Time `json:"firstSeen" yaml:"firstSeen"`
	LastSeen  time.Time `json:"lastSeen" yaml:"lastSeen"`

	// Count is how many times the folded event has occurred (>=1).
	Count int `json:"count" yaml:"count"`
}

type EventLevel string

type Exec struct {
	// Command to execute
	Command []string `json:"command" yaml:"command"`

	// Environment variables
	Env map[string]string `json:"env,omitempty" yaml:"env,omitempty"`
}

type ExecOptions struct {
	// Command is the command to execute
	Command []string

	// Env is a map of environment variables to set for the command
	Env map[string]string

	// WorkingDir is the working directory for the command
	WorkingDir string

	// TTY indicates whether to allocate a pseudo-TTY
	TTY bool

	// TerminalWidth is the initial width of the terminal
	TerminalWidth uint32

	// TerminalHeight is the initial height of the terminal
	TerminalHeight uint32
}

type ExecStream interface {
	// Write writes data to the standard input of the process
	Write(p []byte) (n int, err error)

	// Read reads data from the standard output of the process
	Read(p []byte) (n int, err error)

	// Stderr provides access to the standard error stream of the process
	Stderr() io.Reader

	// ResizeTerminal resizes the terminal (if TTY was enabled)
	ResizeTerminal(width, height uint32) error

	// Signal sends a signal to the process
	Signal(sigName string) error

	// ExitCode returns the exit code after the process has completed
	ExitCode() (int, error)

	// Close terminates the exec session and releases resources
	Close() error
}

type ExposeClientCert struct {
	// CASecret references a Secret holding a PEM CA bundle (data key
	// "ca.crt") used to verify the client certificate. Accepts the same
	// resource-ref shapes as ExposeServiceTLS.Secret.
	CASecret string `json:"caSecret" yaml:"caSecret"`

	// Mode is the verification strictness. v1 supports only "require"
	// (RequireAndVerifyClientCert); empty defaults to "require".
	Mode string `json:"mode,omitempty" yaml:"mode,omitempty"`
}

type ExposeServiceTLS struct {
	// Secret references a Secret resource holding tls.crt + tls.key
	// for operator-supplied certificates. Accepts three shapes:
	//
	//   - "name"                       (resolved in the service's namespace)
	//   - "<namespace>/<name>"         (cross-namespace shorthand)
	//   - "secret:<name>.<ns>.rune"    (FQDN secret ref)
	//
	// Required when Mode is "manual".
	Secret string `json:"secret,omitempty" yaml:"secret,omitempty"`

	// Whether to automatically generate a TLS certificate
	Auto bool `json:"auto,omitempty" yaml:"auto,omitempty"`

	// Mode selects the certificate provisioning strategy.
	// Empty / "manual": operator supplies Secret.
	// "acme": ingress controller obtains a cert from Let's Encrypt
	// (HTTP-01) for Expose.Host. Auto implies Mode=acme.
	// See RUNE-066.
	Mode string `json:"mode,omitempty" yaml:"mode,omitempty"`
}

type FailedInstanceRetentionConfig struct {
	// PerServiceCap is the max number of Failed tombstones kept per
	// service before the oldest is evicted. 0 disables the cap.
	PerServiceCap int `yaml:"per_service_cap,omitempty"`
	// TTL is the max age of a Failed tombstone before it is evicted
	// regardless of cap. 0 disables TTL.
	TTL time.Duration `yaml:"ttl,omitempty"`
	// SnapshotLogBytes caps the per-instance log snapshot captured into
	// Instance.LastLogs at eviction. 0 disables snapshotting. Reserved
	// for v2 — not yet honoured by the eviction path.
	SnapshotLogBytes int `yaml:"snapshot_log_bytes,omitempty"`
}

type Finalizer struct {
	// Unique identifier for the finalizer
	ID string `json:"id"`

	// Type of finalizer
	Type FinalizerType `json:"type"`

	// Status of the finalizer
	Status FinalizerStatus `json:"status"`

	// Error message if finalizer failed
	Error string `json:"error,omitempty"`

	// Dependencies this finalizer has on other finalizers
	Dependencies []FinalizerDependency `json:"dependencies,omitempty"`

	// Timestamps
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
	CompletedAt *time.Time `json:"completed_at,omitempty"`
}

type FinalizerDependency struct {
	// The type of finalizer that must complete before this one
	DependsOn FinalizerType `json:"depends_on"`

	// Whether the dependency is required (true) or optional (false)
	Required bool `json:"required"`
}

type FinalizerInterface interface {
	GetID() string
	GetType() FinalizerType
	Execute(ctx context.Context, service *Service) error
	GetDependencies() []FinalizerDependency
	Validate(service *Service) error
}

type FinalizerStatus string

type FinalizerType string

type Function struct {
	// Unique identifier for the function
	ID string `json:"id" yaml:"id"`

	// Human-readable name for the function
	Name string `json:"name" yaml:"name"`

	// Namespace the function belongs to
	Namespace string `json:"namespace" yaml:"namespace"`

	// Specification of the function
	Spec FunctionSpec `json:"spec" yaml:"spec"`

	// Creation timestamp
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`

	// Last update timestamp
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
}

type FunctionCode struct {
	// Inline source code
	Inline string `json:"inline,omitempty" yaml:"inline,omitempty"`
}

type FunctionDefinition struct {
	// Function metadata and spec
	Function struct {
		// Human-readable name for the function (required)
		Name string `json:"name" yaml:"name"`

		// Namespace the function belongs to (optional, defaults to "default")
		Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`

		// Function specification
		Spec FunctionSpec `json:"spec" yaml:"spec"`
	} `json:"function" yaml:"function"`
}

type FunctionInvocationRequest struct {
	// Payload for the function (JSON-serializable object)
	Payload map[string]interface{} `json:"payload" yaml:"payload"`

	// Timeout override (optional)
	Timeout string `json:"timeout,omitempty" yaml:"timeout,omitempty"`

	// Asynchronous execution flag
	Async bool `json:"async,omitempty" yaml:"async,omitempty"`
}

type FunctionNetworkPolicy struct {
	// Allowed outbound connections
	Allow []FunctionNetworkRule `json:"allow" yaml:"allow"`
}

type FunctionNetworkRule struct {
	// Target host or IP
	Host string `json:"host" yaml:"host"`

	// Allowed ports and protocols (e.g., ["80/tcp", "443/tcp"])
	Ports []string `json:"ports" yaml:"ports"`
}

type FunctionRun struct {
	// Unique identifier for the function run
	ID string `json:"id" yaml:"id"`

	// ID of the function that was executed
	FunctionID string `json:"functionId" yaml:"functionId"`

	// Namespace the function belongs to
	Namespace string `json:"namespace" yaml:"namespace"`

	// Input payload (JSON-serialized)
	Input string `json:"input,omitempty" yaml:"input,omitempty"`

	// Output result (JSON-serialized)
	Output string `json:"output,omitempty" yaml:"output,omitempty"`

	// Execution logs (stdout/stderr)
	Logs string `json:"logs,omitempty" yaml:"logs,omitempty"`

	// Execution status
	Status FunctionRunStatus `json:"status" yaml:"status"`

	// Error message (if status is Failed or TimedOut)
	Error string `json:"error,omitempty" yaml:"error,omitempty"`

	// Start time
	StartTime *time.Time `json:"startTime,omitempty" yaml:"startTime,omitempty"`

	// End time
	EndTime *time.Time `json:"endTime,omitempty" yaml:"endTime,omitempty"`

	// Duration in milliseconds
	DurationMs int64 `json:"durationMs,omitempty" yaml:"durationMs,omitempty"`

	// Invoker information (component/user that triggered the execution)
	InvokedBy string `json:"invokedBy,omitempty" yaml:"invokedBy,omitempty"`

	// Creation timestamp
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`
}

type FunctionRunStatus string

type FunctionSpec struct {
	// Runtime environment (e.g., python3.9, nodejs16, go1.18)
	Runtime string `json:"runtime" yaml:"runtime"`

	// Entrypoint handler (format depends on runtime, e.g., "main.handler")
	Handler string `json:"handler" yaml:"handler"`

	// Maximum execution time (e.g., "30s", "2m")
	Timeout string `json:"timeout" yaml:"timeout"`

	// Memory limit (e.g., "128Mi", "1Gi")
	MemoryLimit string `json:"memoryLimit" yaml:"memoryLimit"`

	// CPU limit (e.g., "100m", "0.5")
	CPULimit string `json:"cpuLimit,omitempty" yaml:"cpuLimit,omitempty"`

	// Function code
	Code FunctionCode `json:"code" yaml:"code"`

	// Static environment variables
	Env map[string]string `json:"env,omitempty" yaml:"env,omitempty"`

	// Network policy for the function
	NetworkPolicy *FunctionNetworkPolicy `json:"networkPolicy,omitempty" yaml:"networkPolicy,omitempty"`
}

type Gateway struct {
	// Unique identifier for the gateway
	ID string `json:"id" yaml:"id"`

	// Human-readable name for the gateway
	Name string `json:"name" yaml:"name"`

	// Namespace the gateway belongs to
	Namespace string `json:"namespace" yaml:"namespace"`

	// Hostname for the gateway (for virtual hosting)
	Hostname string `json:"hostname,omitempty" yaml:"hostname,omitempty"`

	// Whether this is an internal gateway (not exposed outside the mesh)
	Internal bool `json:"internal" yaml:"internal"`

	// Port configurations for the gateway
	Ports []GatewayPort `json:"ports" yaml:"ports"`

	// TLS configuration options
	TLS *GatewayTLS `json:"tls,omitempty" yaml:"tls,omitempty"`

	// Creation timestamp
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`

	// Last update timestamp
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
}

type GatewayPort struct {
	// Port number
	Port int `json:"port" yaml:"port"`

	// Protocol for this port (HTTP, HTTPS, TCP, etc.)
	Protocol string `json:"protocol" yaml:"protocol"`

	// Name for this port (optional)
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
}

type GatewaySpec struct {
	// Gateway metadata and configuration
	Gateway struct {
		// Human-readable name for the gateway (required)
		Name string `json:"name" yaml:"name"`

		// Namespace the gateway belongs to (optional, defaults to "default")
		Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`

		// Hostname for the gateway (for virtual hosting)
		Hostname string `json:"hostname,omitempty" yaml:"hostname,omitempty"`

		// Whether this is an internal gateway (not exposed outside the mesh)
		Internal bool `json:"internal" yaml:"internal"`

		// Port configurations for the gateway
		Ports []GatewayPort `json:"ports" yaml:"ports"`

		// TLS configuration options
		TLS *GatewayTLS `json:"tls,omitempty" yaml:"tls,omitempty"`
	} `json:"gateway" yaml:"gateway"`
}

type GatewayTLS struct {
	// Mode of TLS operation (PASSTHROUGH, SIMPLE, MUTUAL)
	Mode string `json:"mode" yaml:"mode"`

	// Secret name containing TLS credentials
	SecretName string `json:"secretName,omitempty" yaml:"secretName,omitempty"`

	// Minimum TLS version
	MinVersion string `json:"minVersion,omitempty" yaml:"minVersion,omitempty"`

	// Maximum TLS version
	MaxVersion string `json:"maxVersion,omitempty" yaml:"maxVersion,omitempty"`

	// Allow client certificate validation
	ClientCertificate bool `json:"clientCertificate,omitempty" yaml:"clientCertificate,omitempty"`
}

type HTTPRetryPolicy struct {
	// Number of retry attempts
	Attempts int `json:"attempts" yaml:"attempts"`

	// Timeout per retry attempt in milliseconds
	PerTryTimeout int `json:"perTryTimeout,omitempty" yaml:"perTryTimeout,omitempty"`

	// HTTP status codes that trigger a retry
	RetryOn []int `json:"retryOn,omitempty" yaml:"retryOn,omitempty"`
}

type HTTPRewrite struct {
	// URI to replace the matched path with
	URI string `json:"uri,omitempty" yaml:"uri,omitempty"`

	// Host to replace the request host with
	Host string `json:"host,omitempty" yaml:"host,omitempty"`
}

type HTTPRoute struct {
	// Path match for this route (e.g., "/api/v1")
	Path string `json:"path,omitempty" yaml:"path,omitempty"`

	// Path prefix match (e.g., "/api")
	PathPrefix string `json:"pathPrefix,omitempty" yaml:"pathPrefix,omitempty"`

	// HTTP methods this route applies to (GET, POST, etc.)
	Methods []string `json:"methods,omitempty" yaml:"methods,omitempty"`

	// Header matches required
	Headers map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"`

	// Query parameter matches required
	QueryParams map[string]string `json:"queryParams,omitempty" yaml:"queryParams,omitempty"`

	// Destination service and options
	Destination RouteDestination `json:"destination" yaml:"destination"`

	// Rewrite options
	Rewrite *HTTPRewrite `json:"rewrite,omitempty" yaml:"rewrite,omitempty"`

	// Response headers to be added
	AddResponseHeaders map[string]string `json:"addResponseHeaders,omitempty" yaml:"addResponseHeaders,omitempty"`

	// Request headers to be added
	AddRequestHeaders map[string]string `json:"addRequestHeaders,omitempty" yaml:"addRequestHeaders,omitempty"`

	// Timeout for this route in milliseconds
	Timeout int `json:"timeout,omitempty" yaml:"timeout,omitempty"`

	// Retry policy
	Retries *HTTPRetryPolicy `json:"retries,omitempty" yaml:"retries,omitempty"`

	// CORS policy
	CORS *CORSPolicy `json:"cors,omitempty" yaml:"cors,omitempty"`
}

type HealthCheck struct {
	// Liveness probe checks if the instance is running
	Liveness *Probe `json:"liveness,omitempty" yaml:"liveness,omitempty"`

	// Readiness probe checks if the instance is ready to receive traffic
	Readiness *Probe `json:"readiness,omitempty" yaml:"readiness,omitempty"`
}

type HealthCheckResult struct {
	Success    bool
	Message    string
	Duration   time.Duration
	CheckTime  time.Time
	InstanceID string
	CheckType  string
}

type HealthFinalizerInterface interface {
	RemoveInstance(instanceID string) error
}

type IngressCertState string

type IngressCertStatus struct {
	// Host is the hostname the cert is issued for, e.g. api.example.com.
	Host string `json:"host" yaml:"host"`

	// State is one of Pending, Issued, Failed.
	State IngressCertState `json:"state" yaml:"state"`

	// IssuedAt is set when State transitions to Issued.
	IssuedAt *time.Time `json:"issuedAt,omitempty" yaml:"issuedAt,omitempty"`

	// ExpiresAt is the certificate NotAfter from the issued cert.
	ExpiresAt *time.Time `json:"expiresAt,omitempty" yaml:"expiresAt,omitempty"`

	// LastError is populated when State == Failed.
	LastError string `json:"lastError,omitempty" yaml:"lastError,omitempty"`

	// NextRetry is set when State == Failed; the orchestrator
	// schedules the next attempt at this time.
	NextRetry *time.Time `json:"nextRetry,omitempty" yaml:"nextRetry,omitempty"`
}

type IngressConfig struct {
	HTTPAddr  string `yaml:"http_addr,omitempty"`
	HTTPSAddr string `yaml:"https_addr,omitempty"`
}

type IngressRule struct {
	From  []NetworkPolicyPeer `json:"from" yaml:"from"`
	Ports []string            `json:"ports,omitempty" yaml:"ports,omitempty"`
}

type InitStep struct {
	// Name is the step's DNS-1123 identifier, unique within the
	// owning service's InitSteps.
	Name string `json:"name" yaml:"name"`

	// Image is the container image to run. Required when the parent
	// service Runtime is "container" (or unset). For Runtime "process"
	// the field is left empty and the step runs as a subprocess of
	// runed under the parent's process context.
	Image string `json:"image,omitempty" yaml:"image,omitempty"`

	// Command is the executable to run. There is no entrypoint
	// inheritance from the parent image — most init use cases want a
	// different command than the main container.
	Command string `json:"command" yaml:"command"`

	// Args are positional arguments passed to Command.
	Args []string `json:"args,omitempty" yaml:"args,omitempty"`

	// Env is merged on top of the parent service's env. Step-local
	// keys win on conflict.
	Env map[string]string `json:"env,omitempty" yaml:"env,omitempty"`

	// EnvFrom is merged with the parent's EnvFrom. Same precedence
	// rules apply.
	EnvFrom []EnvFromSource `json:"envFrom,omitempty" yaml:"envFrom,omitempty"`

	// Volumes is a filter over the parent service's volume mounts.
	// The default (a nil slice) inherits all parent volumes. An empty
	// non-nil slice mounts none. Each entry must reference a parent
	// VolumeMount.Name.
	Volumes []string `json:"volumes,omitempty" yaml:"volumes,omitempty"`

	// SecretMounts behaves identically to Volumes but for the
	// parent's SecretMounts.
	SecretMounts []string `json:"secretMounts,omitempty" yaml:"secretMounts,omitempty"`

	// ConfigmapMounts behaves identically to Volumes but for the
	// parent's ConfigmapMounts.
	ConfigmapMounts []string `json:"configmapMounts,omitempty" yaml:"configmapMounts,omitempty"`

	// Resources optionally overrides the inherited parent Resources.
	// Init for databases is often more I/O- and CPU-heavy than steady
	// state, so artificial low defaults would OOM-kill init.
	Resources *Resources `json:"resources,omitempty" yaml:"resources,omitempty"`

	// RunIf decides whether to execute the step on a given instance
	// start. Zero value is treated as Type=freshVolume.
	RunIf RunIf `json:"runIf,omitempty" yaml:"runIf,omitempty"`

	// Timeout is the per-step ceiling. Zero defers to the cast-level
	// timeout enforced by the controller.
	Timeout time.Duration `json:"timeout,omitempty" yaml:"timeout,omitempty"`

	// RestartPolicy controls per-step retry behaviour. Default
	// OnFailure (bounded retries inside the step).
	RestartPolicy InitStepRestartPolicy `json:"restartPolicy,omitempty" yaml:"restartPolicy,omitempty"`

	// SecurityContext optionally overrides container security knobs for
	// this step (seccomp profile, Linux capabilities, privileged). When
	// nil the step inherits the runtime defaults. Setting privileged=true
	// or seccompProfile.type=unconfined requires the services.privileged
	// policy verb; the server rejects requests that lack it.
	SecurityContext *SecurityContext `json:"securityContext,omitempty" yaml:"securityContext,omitempty"`
}

type InitStepRestartPolicy string

type InitStepState struct {
	// Name matches Service.InitSteps[*].Name.
	Name string `json:"name" yaml:"name"`

	// Status is the lifecycle state.
	Status InitStepStatus `json:"status" yaml:"status"`

	// ExitCode is the process/container exit code. Zero by default;
	// only meaningful when Status is Succeeded or Failed.
	ExitCode int `json:"exitCode,omitempty" yaml:"exitCode,omitempty"`

	// StartedAt is the wall-clock time the step entered Running.
	StartedAt time.Time `json:"startedAt,omitempty" yaml:"startedAt,omitempty"`

	// FinishedAt is the wall-clock time the step left Running.
	FinishedAt time.Time `json:"finishedAt,omitempty" yaml:"finishedAt,omitempty"`

	// Attempts is the number of executions tried so far (>= 1 once
	// the step has run at least once). Used by RestartPolicy=OnFailure.
	Attempts int `json:"attempts,omitempty" yaml:"attempts,omitempty"`

	// Reason is one of the InitStepReason* slugs (empty on success).
	Reason string `json:"reason,omitempty" yaml:"reason,omitempty"`

	// Message is a single-line human explanation copied to
	// Service.StatusMessage on rollup.
	Message string `json:"message,omitempty" yaml:"message,omitempty"`

	// LogRef is an opaque handle the log subsystem can resolve to the
	// step's stdout/stderr slice.
	LogRef string `json:"logRef,omitempty" yaml:"logRef,omitempty"`
}

type InitStepStatus string

type Instance struct {
	NamespacedResource `json:"-" yaml:"-"`

	// Runner type for the instance
	Runner RunnerType `json:"runner" yaml:"runner"`

	// Unique identifier for the instance
	ID string `json:"id" yaml:"id"`

	// Namespace of the instance
	Namespace string `json:"namespace" yaml:"namespace"`

	// Human-readable name for the instance
	Name string `json:"name" yaml:"name"`

	// ID of the service this instance belongs to
	ServiceID string `json:"serviceId" yaml:"serviceId"`

	// Name of the service this instance belongs to
	ServiceName string `json:"serviceName" yaml:"serviceName"`

	// Ordinal is the per-replica slot index (0-based) assigned by the
	// reconciler at creation. It is the authoritative source of per-instance
	// identity for stable resources — notably per-replica volume claimTemplates,
	// which bind to "<mount>-<service>-<ordinal>". Keeping the ordinal as an
	// explicit field (rather than parsing it back out of Name) decouples that
	// binding from the instance-name format, so the name can move to a unique
	// per-lifetime form (RUNE issue #84) without breaking volume rebinding.
	Ordinal int `json:"ordinal" yaml:"ordinal"`

	// Labels are denormalized from the parent Service's user labels at creation
	// (and, once a placement scheduler exists, will also carry the assigned
	// node's topology labels — see CreateInstance). They form the user-defined
	// LogQL stream dimensions for this instance's logs and the substrate for
	// future node-affinity / topology-spread scheduling. Low-cardinality only —
	// high-cardinality data belongs in log content/fields, not stream labels.
	Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`

	// ID of the node running this instance
	NodeID string `json:"nodeId" yaml:"nodeId"`

	// IP address assigned to this instance
	IP string `json:"ip" yaml:"ip"`

	// Status of the instance
	Status InstanceStatus `json:"status" yaml:"status"`

	// StatusReason is a short, machine-friendly slug for the current
	// Status, regardless of whether Status is a terminal failure state.
	// Mirrors Service.StatusReason / Volume.StatusReason. Set by the
	// reconciler on every status transition — including non-terminal
	// states such as Pending while a precondition (volume, secret,
	// image) is still unmet. Empty only when Status is Running.
	// Vocabulary is the slug set produced by classifyCreateError
	// (e.g. "VolumeNotReady", "StorageClassMissing", "SecretNotFound").
	// On a Failed/Stalled instance this converges with FailureReason.
	StatusReason string `json:"statusReason,omitempty" yaml:"statusReason,omitempty"`

	// Detailed status information
	StatusMessage string `json:"statusMessage,omitempty" yaml:"statusMessage,omitempty"`

	// Container ID or process ID
	ContainerID string `json:"containerId,omitempty" yaml:"containerId,omitempty"`

	// Process ID for process runner
	PID int `json:"pid,omitempty" yaml:"pid,omitempty"`

	// Creation timestamp
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`

	// Last update timestamp
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`

	// LastTransitionAt is when Status last changed value. Drives the
	// "Pending for 5m" age in `rune describe` and lets the reconciler
	// distinguish a genuinely-stuck resource from a freshly-updated
	// one. Distinct from UpdatedAt, which moves on any field write.
	// nil until the first reconciler-observed transition.
	LastTransitionAt *time.Time `json:"lastTransitionAt,omitempty" yaml:"lastTransitionAt,omitempty"`

	// Process-specific configuration for process runner
	Process *ProcessSpec `json:"process,omitempty" yaml:"process,omitempty"`

	// Execution configuration for commands and environment
	Exec *Exec `json:"exec,omitempty" yaml:"exec,omitempty"`

	// Resources requirements for the instance
	Resources *Resources `json:"resources,omitempty" yaml:"resources,omitempty"`

	// Environment variables for the instance
	Environment map[string]string `json:"environment,omitempty" yaml:"environment,omitempty"`

	// Metadata contains additional information about the instance
	// Use for storing system properties that aren't part of the core spec
	Metadata *InstanceMetadata `json:"metadata,omitempty" yaml:"metadata,omitempty"`

	// InitStates records the per-instance execution state for each
	// of the parent service's InitSteps (RUNE-121). One entry per
	// declared step, in declaration order. Empty for instances of
	// services with no init steps.
	InitStates []InitStepState `json:"initStates,omitempty" yaml:"initStates,omitempty"`

	// SecurityContext is inherited from the parent service's
	// SecurityContext and applied to the main container by the runner.
	// nil means runtime defaults.
	SecurityContext *SecurityContext `json:"securityContext,omitempty" yaml:"securityContext,omitempty"`

	// FailedAt is the timestamp the instance entered the Failed state.
	// Used by the reconciler's failed-instance retention GC to drive
	// per-service cap + TTL eviction. nil for instances that have never
	// failed.
	FailedAt *time.Time `json:"failedAt,omitempty" yaml:"failedAt,omitempty"`

	// FailureReason is a short, machine-friendly slug describing why the
	// instance failed (e.g. "HealthCheckFailure", "ImagePullFailed",
	// "OOMKilled"). Set at the moment of the Failed transition.
	FailureReason string `json:"failureReason,omitempty" yaml:"failureReason,omitempty"`

	// Usage is a live resource-usage sample attached by the API read path
	// from runners that implement the StatsProvider capability. TRANSIENT:
	// excluded from store serialization (json/yaml "-") so stale samples
	// are never persisted — it exists only on instances flowing through a
	// read RPC response.
	Usage *InstanceUsage `json:"-" yaml:"-"`

	// LastLogs is a snapshot of the last N bytes of the instance's stdout
	// and stderr, captured before the container is removed (either during
	// a restart-on-failure cycle or at retention-GC eviction). Lets
	// `rune logs --previous` show what the dead container said even after
	// the container itself is gone. Bounded by runed config
	// (failedInstanceRetention.snapshotLogBytes, default 200 KB).
	LastLogs []byte `json:"lastLogs,omitempty" yaml:"lastLogs,omitempty"`

	// LastLogsCapturedAt records when LastLogs was snapshotted so the
	// CLI can show "logs as of <time>" instead of pretending they're live.
	LastLogsCapturedAt *time.Time `json:"lastLogsCapturedAt,omitempty" yaml:"lastLogsCapturedAt,omitempty"`

	// LastLogsTruncated is true when LastLogs is a tail-only snapshot
	// (we hit the byte cap). The CLI shows a "[truncated]" marker so
	// operators know there was more output above what's preserved.
	LastLogsTruncated bool `json:"lastLogsTruncated,omitempty" yaml:"lastLogsTruncated,omitempty"`

	// CreateAttempts counts how many times the orchestrator has tried
	// to stand this instance record up (resolve mounts → run init →
	// runner.Create → runner.Start). Persisted on the record so a runed
	// restart does not reset progress against a stable precondition
	// failure (e.g. StorageClassMissing). Zeroed on first success.
	CreateAttempts int `json:"createAttempts,omitempty" yaml:"createAttempts,omitempty"`

	// ContainerEverCreatedAt is the wall-clock time `runner.Create`
	// first succeeded for this instance ID. The reconciler uses this
	// to distinguish "create has never succeeded" (precondition
	// failure — keep retrying the same record) from "container
	// vanished" (docker rm, host reboot — tombstone and recreate).
	// nil until the first successful runner.Create.
	ContainerEverCreatedAt *time.Time `json:"containerEverCreatedAt,omitempty" yaml:"containerEverCreatedAt,omitempty"`

	// NextCreateAttemptAt is the earliest wall-clock time the
	// reconciler may try CreateInstance again for this record.
	// Populated after every failed attempt as an exponential backoff
	// (30s → 1m → 2m → 4m → 5m cap). Reconciler ticks before this
	// time leave the record alone. nil means "ready now" or "not in
	// retry mode". Cleared on first success and on operator restart.
	NextCreateAttemptAt *time.Time `json:"nextCreateAttemptAt,omitempty" yaml:"nextCreateAttemptAt,omitempty"`
}

type InstanceAction struct {
	Type       InstanceActionType
	Service    string
	Namespace  string
	InstanceID string
	Timestamp  time.Time
}

type InstanceActionType string

type InstanceFinalizerInterface interface {
	StopInstance(ctx context.Context, instance *Instance) error
	DeleteInstance(ctx context.Context, instance *Instance) error
}

type InstanceHealthStatus struct {
	InstanceID  string
	Liveness    bool
	Readiness   bool
	LastChecked time.Time
}

type InstanceIdentity struct {
	// InstanceID is the orchestrator-assigned instance ID. Useful
	// for log correlation; not used for matching.
	InstanceID string `json:"instanceId" yaml:"instanceId"`

	// Service is the service name (no namespace).
	Service string `json:"service" yaml:"service"`

	// Namespace the service belongs to.
	Namespace string `json:"namespace" yaml:"namespace"`
}

type InstanceMetadata struct {
	// Image is the image that the instance is running
	Image string `json:"image,omitempty" yaml:"image,omitempty"`

	// Command is the executable to run inside the container,
	// propagated from Service.Command. Maps to Docker's Entrypoint:
	// it replaces the image's baked-in ENTRYPOINT. Empty leaves the
	// image's ENTRYPOINT untouched.
	Command string `json:"command,omitempty" yaml:"command,omitempty"`

	// Args are positional arguments to Command, propagated from
	// Service.Args. Maps to Docker's Cmd: it replaces the image's
	// baked-in CMD. nil leaves the image's CMD untouched.
	Args []string `json:"args,omitempty" yaml:"args,omitempty"`

	// ImagePull controls when the runner pulls the container image
	// ("always", "missing", "never"). Propagated from the parent
	// Service spec; empty defaults to "always".
	ImagePull string `json:"imagePull,omitempty" yaml:"imagePull,omitempty"`

	// ServiceGeneration is the generation of the service that the instance belongs to
	ServiceGeneration int64 `json:"serviceGeneration,omitempty" yaml:"serviceGeneration,omitempty"`

	// DeletionTimestamp is the timestamp when the instance was marked for deletion
	DeletionTimestamp *time.Time `json:"deletionTimestamp,omitempty" yaml:"deletionTimestamp,omitempty"`

	// RestartCount is the number of times this instance has been restarted
	RestartCount int `json:"restartCount,omitempty" yaml:"restartCount,omitempty"`

	// SecretMounts contains the resolved secret mount information for this instance
	SecretMounts []ResolvedSecretMount `json:"secretMounts,omitempty" yaml:"secretMounts,omitempty"`

	// ConfigmapMounts contains the resolved config mount information for this instance
	ConfigmapMounts []ResolvedConfigmapMount `json:"configMounts,omitempty" yaml:"configMounts,omitempty"`

	// VolumeMounts contains the resolved volume mount information for
	// this instance: each entry maps a Service.VolumeMount to the
	// concrete host-side source path produced by the storage driver.
	// Populated by the orchestrator's instance controller from the bound
	// Volume's Handle.
	VolumeMounts []ResolvedVolumeMount `json:"volumeMounts,omitempty" yaml:"volumeMounts,omitempty"`

	// Ports declared by the service (propagated for runner use)
	Ports []ServicePort `json:"ports,omitempty" yaml:"ports,omitempty"`

	// Expose specification from the service (propagated for runner use)
	Expose *ServiceExpose `json:"expose,omitempty" yaml:"expose,omitempty"`

	// Resolved exposed endpoint on host (best-effort)
	ExposedHost     string `json:"exposedHost,omitempty" yaml:"exposedHost,omitempty"`
	ExposedHostPort int    `json:"exposedHostPort,omitempty" yaml:"exposedHostPort,omitempty"`

	// ContainerIP is the IP assigned to the container on its primary
	// Docker network. Recorded by the runner on Start; consumed by the
	// agent to map source IPs to service identity for policy
	// enforcement.
	ContainerIP string `json:"containerIp,omitempty" yaml:"containerIp,omitempty"`
}

type InstanceStatus string

type InstanceStatusInfo struct {
	Status        InstanceStatus
	StatusMessage string
	InstanceID    string
	NodeID        string
	CreatedAt     time.Time
	UpdatedAt     time.Time
}

type InstanceUsage struct {
	// CPUPercent is CPU usage as a share of the WHOLE HOST, 0–100 — the
	// same denominator as node-level CPU on HealthService, so instance
	// bars and node bars compare 1:1. Negative when unknown.
	CPUPercent float64

	// MemUsedBytes is memory used in bytes (cgroup usage minus inactive
	// file cache, matching `docker stats` semantics).
	MemUsedBytes uint64

	// MemLimitBytes is the container's cgroup memory limit, which equals
	// the host total when the container is uncapped. 0 when unknown.
	MemLimitBytes uint64
}

type Job struct {
	// Unique identifier for the job
	ID string `json:"id" yaml:"id"`

	// Human-readable name for the job
	Name string `json:"name" yaml:"name"`

	// Namespace the job belongs to
	Namespace string `json:"namespace" yaml:"namespace"`

	// Schedule in cron format (if this is a scheduled job)
	Schedule string `json:"schedule,omitempty" yaml:"schedule,omitempty"`

	// Template defining the job execution environment
	Template JobTemplate `json:"template" yaml:"template"`

	// Optional array job configuration
	Array *JobArray `json:"array,omitempty" yaml:"array,omitempty"`

	// Retry policy for failed job runs
	RetryPolicy *RetryPolicy `json:"retryPolicy,omitempty" yaml:"retryPolicy,omitempty"`

	// How to handle concurrent runs (for scheduled jobs)
	ConcurrencyPolicy string `json:"concurrencyPolicy,omitempty" yaml:"concurrencyPolicy,omitempty"`

	// Number of successful run records to keep
	SuccessfulRunsHistoryLimit int `json:"successfulRunsHistoryLimit,omitempty" yaml:"successfulRunsHistoryLimit,omitempty"`

	// Number of failed run records to keep
	FailedRunsHistoryLimit int `json:"failedRunsHistoryLimit,omitempty" yaml:"failedRunsHistoryLimit,omitempty"`

	// Creation timestamp
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`

	// Last update timestamp
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
}

type JobArray struct {
	// Number of runs to create in the array
	Count int `json:"count" yaml:"count"`

	// Optional parallelism limit (max concurrent runs)
	Parallelism int `json:"parallelism,omitempty" yaml:"parallelism,omitempty"`
}

type JobFile struct {
	// Job definition
	Job *JobSpec `json:"job,omitempty" yaml:"job,omitempty"`

	// Multiple job definitions
	Jobs []JobSpec `json:"jobs,omitempty" yaml:"jobs,omitempty"`
}

type JobRun struct {
	// Unique identifier for the job run
	ID string `json:"id" yaml:"id"`

	// Human-readable name for the job run
	Name string `json:"name" yaml:"name"`

	// ID of the job this run belongs to
	JobID string `json:"jobId" yaml:"jobId"`

	// Namespace the job run belongs to
	Namespace string `json:"namespace" yaml:"namespace"`

	// Node this job run is/was scheduled on
	NodeID string `json:"nodeId,omitempty" yaml:"nodeId,omitempty"`

	// For array jobs, the index of this run in the array
	ArrayIndex int `json:"arrayIndex,omitempty" yaml:"arrayIndex,omitempty"`

	// Status of the job run
	Status JobRunStatus `json:"status" yaml:"status"`

	// Detailed status message
	StatusMessage string `json:"statusMessage,omitempty" yaml:"statusMessage,omitempty"`

	// Exit code if the job has completed
	ExitCode int `json:"exitCode,omitempty" yaml:"exitCode,omitempty"`

	// Number of restart attempts so far
	RestartCount int `json:"restartCount,omitempty" yaml:"restartCount,omitempty"`

	// Start time
	StartTime *time.Time `json:"startTime,omitempty" yaml:"startTime,omitempty"`

	// Completion time
	CompletionTime *time.Time `json:"completionTime,omitempty" yaml:"completionTime,omitempty"`

	// Creation timestamp
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`

	// Last update timestamp
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
}

type JobRunStatus string

type JobSpec struct {
	// Human-readable name for the job (required)
	Name string `json:"name" yaml:"name"`

	// Namespace the job belongs to (optional, defaults to "default")
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`

	// Schedule in cron format (if this is a scheduled job)
	Schedule string `json:"schedule,omitempty" yaml:"schedule,omitempty"`

	// Template defining the job execution environment
	Template JobTemplate `json:"template" yaml:"template"`

	// Optional array job configuration
	Array *JobArray `json:"array,omitempty" yaml:"array,omitempty"`

	// Retry policy for failed job runs
	RetryPolicy *RetryPolicy `json:"retryPolicy,omitempty" yaml:"retryPolicy,omitempty"`

	// How to handle concurrent runs (for scheduled jobs)
	ConcurrencyPolicy string `json:"concurrencyPolicy,omitempty" yaml:"concurrencyPolicy,omitempty"`

	// Number of successful run records to keep
	SuccessfulRunsHistoryLimit int `json:"successfulRunsHistoryLimit,omitempty" yaml:"successfulRunsHistoryLimit,omitempty"`

	// Number of failed run records to keep
	FailedRunsHistoryLimit int `json:"failedRunsHistoryLimit,omitempty" yaml:"failedRunsHistoryLimit,omitempty"`
}

type JobTemplate struct {
	// Container image for the job
	Image string `json:"image" yaml:"image"`

	// Command to run in the container (overrides image CMD)
	Command string `json:"command,omitempty" yaml:"command,omitempty"`

	// Arguments to the command
	Args []string `json:"args,omitempty" yaml:"args,omitempty"`

	// Environment variables for the job
	Env map[string]string `json:"env,omitempty" yaml:"env,omitempty"`

	// Resource requirements for the job
	Resources Resources `json:"resources,omitempty" yaml:"resources,omitempty"`

	// Volumes to mount in the job container
	Volumes []VolumeMount `json:"volumes,omitempty" yaml:"volumes,omitempty"`

	// Secret mounts
	SecretMounts []SecretMount `json:"secretMounts,omitempty" yaml:"secretMounts,omitempty"`

	// Config mounts
	ConfigmapMounts []ConfigmapMount `json:"configmapMounts,omitempty" yaml:"configmapMounts,omitempty"`
}

type KEKConfig struct {
	Source     string            `yaml:"source,omitempty"`
	File       string            `yaml:"file,omitempty"`
	Passphrase *PassphraseConfig `yaml:"passphrase,omitempty"`
}

type KeyToPath struct {
	// Key in the Secret or Config
	Key string `json:"key" yaml:"key"`

	// Path where the key should be mounted (relative to mount point)
	Path string `json:"path" yaml:"path"`
}

type LimitsConfig struct {
	MaxObjectBytes   int `yaml:"max_object_bytes,omitempty"`
	MaxKeyNameLength int `yaml:"max_key_name_length,omitempty"`
}

type LocalInstances struct {
	// NodeID is the identity of the node these instances live on.
	NodeID string `json:"nodeId" yaml:"nodeId"`

	// Instances maps a container IP (e.g. "172.17.0.5") to the
	// service identity that owns it.
	Instances map[string]InstanceIdentity `json:"instances" yaml:"instances"`
}

type LogConfig struct {
	Level  string `yaml:"level,omitempty"`
	Format string `yaml:"format,omitempty"`
}

type LogOptions struct {
	Follow     bool
	Since      time.Time
	Until      time.Time
	Tail       int
	Timestamps bool
	ShowLogs   bool   // Show container/process logs
	ShowEvents bool   // Show lifecycle events
	ShowStatus bool   // Show status changes
	Pattern    string // Filter logs by pattern
}

type LokiConfig struct {
	// URL is the Loki HTTP endpoint (e.g. http://loki:3100).
	URL string `yaml:"url,omitempty"`
	// TenantID is sent as X-Scope-OrgID for multi-tenant Loki.
	TenantID string `yaml:"tenant_id,omitempty"`
}

type MemoryConfig struct {
	DefaultRequest string `yaml:"default_request,omitempty"`
	DefaultLimit   string `yaml:"default_limit,omitempty"`
}

type Namespace struct {
	// Unique identifier for the namespace
	ID string `json:"id" yaml:"id"`

	// Human-readable name for the namespace
	Name string `json:"name" yaml:"name"`

	// Optional description for the namespace
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Optional resource quotas for this namespace
	Quota *NamespaceQuota `json:"quota,omitempty" yaml:"quota,omitempty"`

	// Labels attached to the namespace for organization
	Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`

	// Creation timestamp
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`

	// Last update timestamp
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
}

type NamespaceQuota struct {
	// Maximum CPU allocation for all resources in the namespace (millicores)
	CPU int64 `json:"cpu,omitempty" yaml:"cpu,omitempty"`

	// Maximum memory allocation for all resources in the namespace (bytes)
	Memory int64 `json:"memory,omitempty" yaml:"memory,omitempty"`

	// Maximum storage allocation for all resources in the namespace (bytes)
	Storage int64 `json:"storage,omitempty" yaml:"storage,omitempty"`

	// Maximum number of services allowed in the namespace
	Services int `json:"services,omitempty" yaml:"services,omitempty"`

	// Maximum number of jobs allowed in the namespace
	Jobs int `json:"jobs,omitempty" yaml:"jobs,omitempty"`

	// Maximum number of instances (all services combined) allowed in the namespace
	Instances int `json:"instances,omitempty" yaml:"instances,omitempty"`
}

type NamespaceSpec struct {
	// Human-readable name for the namespace (required)
	Name string `json:"name" yaml:"name"`

	// Optional description for the namespace
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Optional resource quotas for this namespace
	Quota *NamespaceQuota `json:"quota,omitempty" yaml:"quota,omitempty"`

	// Labels attached to the namespace for organization
	Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
}

type NamespacedName struct {
	Namespace string `json:"namespace" yaml:"namespace"`
	Name      string `json:"name" yaml:"name"`
}

type NamespacedResource interface {
	NamespacedName() NamespacedName
	GetID() string // For resources that also have an ID
	GetResourceType() ResourceType
}

type NetworkPolicyPeer struct {
	Service         string            `json:"service,omitempty" yaml:"service,omitempty"`
	Namespace       string            `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	ServiceSelector map[string]string `json:"serviceSelector,omitempty" yaml:"serviceSelector,omitempty"`
	CIDR            string            `json:"cidr,omitempty" yaml:"cidr,omitempty"`
}

type NetworkingConfig struct {
	ClusterCIDR string `yaml:"cluster_cidr,omitempty"`
	DevMode     bool   `yaml:"dev_mode,omitempty"`
}

type Node struct {
	// Unique identifier for the node
	ID string `json:"id" yaml:"id"`

	// Human-readable name for the node
	Name string `json:"name" yaml:"name"`

	// IP address or hostname of the node
	Address string `json:"address" yaml:"address"`

	// Labels attached to the node for scheduling decisions
	Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`

	// Available resources on this node
	Resources NodeResources `json:"resources" yaml:"resources"`

	// Status of the node
	Status NodeStatus `json:"status" yaml:"status"`

	// StatusReason is a short, machine-friendly slug explaining the
	// current Status (e.g. "HeartbeatTimeout", "DrainRequested").
	// Mirrors Service/Instance/Volume StatusReason. Empty when the
	// node is Ready.
	StatusReason string `json:"statusReason,omitempty" yaml:"statusReason,omitempty"`

	// StatusMessage is a human-readable sentence explaining StatusReason,
	// surfaced by `rune describe node`.
	StatusMessage string `json:"statusMessage,omitempty" yaml:"statusMessage,omitempty"`

	// Creation timestamp
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`

	// Last heartbeat timestamp
	LastHeartbeat time.Time `json:"lastHeartbeat" yaml:"lastHeartbeat"`
}

type NodeConfig struct {
	Role string `yaml:"role,omitempty"`
}

type NodeResources struct {
	// Available CPU in millicores (1000m = 1 CPU)
	CPU int64 `json:"cpu" yaml:"cpu"`

	// Available memory in bytes
	Memory int64 `json:"memory" yaml:"memory"`
}

type NodeStatus string

type ObservabilityConfig struct {
	// Enabled turns the forwarder + log store on. Default false (opt-in):
	// the embedded store is lightweight but logging every workload line is
	// an operator choice, so a bare install stays on the live ephemeral
	// stream until [observability] is switched on.
	Enabled bool `yaml:"enabled,omitempty"`

	// Backend selects the log store: embedded (default, in-process), or the
	// optional clickhouse / loki sinks.
	Backend string `yaml:"backend,omitempty"`

	// RetentionDays bounds record age: the embedded store's sweep, and the
	// ClickHouse table's DELETE TTL. 0 uses the backend default. Loki manages
	// its own retention server-side.
	RetentionDays int `yaml:"retention_days,omitempty"`

	// Loki configures the loki backend. Parallel to internal/config.LokiConfig.
	Loki *LokiConfig `yaml:"loki,omitempty"`

	// ClickHouse configures the clickhouse backend, including S3 tiering.
	// Parallel to internal/config.ClickHouseConfig.
	ClickHouse *ClickHouseConfig `yaml:"clickhouse,omitempty"`
}

type OwnedBy struct {
	// Release is the owning release name.
	Release string `json:"release" yaml:"release"`
	// Revision is the release revision that created or last touched the resource.
	Revision int `json:"revision" yaml:"revision"`
	// Manager identifies what manages the resource; "runeset" today.
	Manager string `json:"manager" yaml:"manager"`
}

type OwnerRef struct {
	ResourceType ResourceType `json:"resourceType" yaml:"resourceType"`
	Namespace    string       `json:"namespace" yaml:"namespace"`
	Name         string       `json:"name" yaml:"name"`
}

type PassphraseConfig struct {
	Enabled bool   `yaml:"enabled"`
	Env     string `yaml:"env,omitempty"`
}

type PluginConfig struct {
	Dir     string   `yaml:"dir,omitempty"`
	Enabled []string `yaml:"enabled,omitempty"`
}

type Policy struct {
	ID          string       `json:"id" yaml:"id"`
	Name        string       `json:"name" yaml:"name"` // DNS-1123 unique name within a namespace
	Description string       `json:"description,omitempty" yaml:"description,omitempty"`
	Rules       []PolicyRule `json:"rules" yaml:"rules"`
	Builtin     bool         `json:"builtin" yaml:"builtin"`
}

type PolicyRule struct {
	Resource  string   `json:"resource" yaml:"resource"`
	Verbs     []string `json:"verbs" yaml:"verbs"`
	Namespace string   `json:"namespace,omitempty" yaml:"namespace,omitempty"`
}

type Probe struct {
	// Type of probe (http, tcp, exec)
	Type string `json:"type" yaml:"type"`

	// HTTP path for http probe
	Path string `json:"path,omitempty" yaml:"path,omitempty"`

	// Host overrides the default probe target. Empty means use the
	// instance's container IP (production) or localhost (process
	// runner / dev fallback). Set this to "127.0.0.1" when targeting
	// a hostPort published by the service on macOS Docker Desktop.
	Host string `json:"host,omitempty" yaml:"host,omitempty"`

	// Port to connect to
	Port int `json:"port" yaml:"port"`

	// Command to execute for exec probe
	Command []string `json:"command,omitempty" yaml:"command,omitempty"`

	// Initial delay seconds before starting checks
	InitialDelaySeconds int `json:"initialDelaySeconds,omitempty" yaml:"initialDelaySeconds,omitempty"`

	// Interval between checks in seconds
	IntervalSeconds int `json:"intervalSeconds,omitempty" yaml:"intervalSeconds,omitempty"`

	// Timeout for the probe in seconds
	TimeoutSeconds int `json:"timeoutSeconds,omitempty" yaml:"timeoutSeconds,omitempty"`

	// Failure threshold for the probe
	FailureThreshold int `json:"failureThreshold,omitempty" yaml:"failureThreshold,omitempty"`

	// Success threshold for the probe
	SuccessThreshold int `json:"successThreshold,omitempty" yaml:"successThreshold,omitempty"`
}

type ProcessSecurityContext struct {
	// User to run as
	User string `json:"user,omitempty" yaml:"user,omitempty"`

	// Group to run as
	Group string `json:"group,omitempty" yaml:"group,omitempty"`

	// Run with read-only filesystem
	ReadOnlyFS bool `json:"readOnlyFS,omitempty" yaml:"readOnlyFS,omitempty"`

	// Linux capabilities to add
	Capabilities []string `json:"capabilities,omitempty" yaml:"capabilities,omitempty"`

	// Allowed syscalls (seccomp)
	AllowedSyscalls []string `json:"allowedSyscalls,omitempty" yaml:"allowedSyscalls,omitempty"`

	// Denied syscalls (seccomp)
	DeniedSyscalls []string `json:"deniedSyscalls,omitempty" yaml:"deniedSyscalls,omitempty"`
}

type ProcessSpec struct {
	// Command to run
	Command string `json:"command" yaml:"command"`

	// Command arguments
	Args []string `json:"args,omitempty" yaml:"args,omitempty"`

	// Working directory for the process
	WorkingDir string `json:"workingDir,omitempty" yaml:"workingDir,omitempty"`

	// Security settings
	SecurityContext *ProcessSecurityContext `json:"securityContext,omitempty" yaml:"securityContext,omitempty"`
}

type ReclaimPolicy string

type RegistryAuth struct {
	Type     string `json:"type,omitempty" yaml:"type,omitempty"` // basic | token | ecr
	Username string `json:"username,omitempty" yaml:"username,omitempty"`
	Password string `json:"password,omitempty" yaml:"password,omitempty"`
	Token    string `json:"token,omitempty" yaml:"token,omitempty"`
	Region   string `json:"region,omitempty" yaml:"region,omitempty"`
}

type Release struct {
	// ID is a stable unique identifier for the release.
	ID string `json:"id" yaml:"id"`

	// Name is unique within the home namespace. Equals the --release value,
	// defaulting to the runeset manifest name, then the file/dir base name.
	Name string `json:"name" yaml:"name"`

	// Namespace is the release's home namespace.
	Namespace string `json:"namespace" yaml:"namespace"`

	// Status is the current lifecycle state of the release.
	Status ReleaseStatus `json:"status" yaml:"status"`

	// Revision increments on every successful cast of this release.
	Revision int `json:"revision" yaml:"revision"`

	// Source records where the runeset came from (dir, tgz, github, url) plus
	// the ref/digest, so a revision is reproducible.
	Source ReleaseSource `json:"source" yaml:"source"`

	// Manifest is the runeset.yaml that was deployed for this revision.
	Manifest RunesetManifest `json:"manifest" yaml:"manifest"`

	// Values is the fully-merged value set used to render this revision, kept
	// for diff and rollback.
	Values map[string]interface{} `json:"values,omitempty" yaml:"values,omitempty"`

	// RenderedDigest is a checksum of the rendered castfile set, used as the
	// baseline for drift detection.
	RenderedDigest string `json:"renderedDigest,omitempty" yaml:"renderedDigest,omitempty"`

	// Owns is the authoritative set of resources this revision owns.
	Owns []OwnerRef `json:"owns,omitempty" yaml:"owns,omitempty"`

	// References records shared/cluster-scoped resources this release depends on
	// but does NOT own (and will never delete) — e.g. a pre-existing StorageClass
	// or Namespace it did not create (Decision D2).
	References []OwnerRef `json:"references,omitempty" yaml:"references,omitempty"`

	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
}

type ReleaseSource struct {
	// Type mirrors RunesetSourceType (directory, package-archive, github, ...).
	Type RunesetSourceType `json:"type" yaml:"type"`
	// Location is the raw source argument (path, URL, or github shorthand).
	Location string `json:"location" yaml:"location"`
	// Ref is the resolved version reference where applicable (git ref, tag).
	Ref string `json:"ref,omitempty" yaml:"ref,omitempty"`
	// Digest is the archive/content checksum where available.
	Digest string `json:"digest,omitempty" yaml:"digest,omitempty"`
}

type ReleaseStatus string

type ResolvedConfigmapMount struct {
	// Name of the mount (for identification)
	Name string `json:"name" yaml:"name"`

	// Path where the config should be mounted
	MountPath string `json:"mountPath" yaml:"mountPath"`

	// Resolved config data (key -> value)
	Data map[string]string `json:"data" yaml:"data"`

	// Optional: specific keys to project from the config
	Items []KeyToPath `json:"items,omitempty" yaml:"items,omitempty"`
}

type ResolvedSecretMount struct {
	// Name of the mount (for identification)
	Name string `json:"name" yaml:"name"`

	// Path where the secret should be mounted
	MountPath string `json:"mountPath" yaml:"mountPath"`

	// Resolved secret data (key -> value)
	Data map[string]string `json:"data" yaml:"data"`

	// Optional: specific keys to project from the secret
	Items []KeyToPath `json:"items,omitempty" yaml:"items,omitempty"`
}

type ResolvedVolumeMount struct {
	// Name is the mount's service-local identifier (matches
	// Service.VolumeMount.Name).
	Name string `json:"name" yaml:"name"`

	// MountPath is the absolute container path the volume is mounted at.
	MountPath string `json:"mountPath" yaml:"mountPath"`

	// Source is the host-side path to bind into the container.
	Source string `json:"source" yaml:"source"`

	// VolumeName is the name of the bound Volume resource (in the same
	// namespace as the owning service unless the mount used an FQDN).
	VolumeName string `json:"volumeName" yaml:"volumeName"`

	// VolumeNamespace is the namespace of the bound Volume.
	VolumeNamespace string `json:"volumeNamespace,omitempty" yaml:"volumeNamespace,omitempty"`

	// ReadOnly mounts the volume read-only inside the container.
	ReadOnly bool `json:"readOnly,omitempty" yaml:"readOnly,omitempty"`

	// SubPath, if non-empty, selects a sub-path within the volume.
	SubPath string `json:"subPath,omitempty" yaml:"subPath,omitempty"`
}

type Resource interface {
	// String returns a unique identifier for the resource
	String() string

	// Equals checks if two resources are functionally equivalent
	Equals(other Resource) bool
}

type ResourceConfig struct {
	CPU    *CPUConfig    `yaml:"cpu,omitempty"`
	Memory *MemoryConfig `yaml:"memory,omitempty"`
}

type ResourceLimit struct {
	// Requested resources (guaranteed)
	Request string `json:"request,omitempty" yaml:"request,omitempty"`

	// Maximum resources (limit)
	Limit string `json:"limit,omitempty" yaml:"limit,omitempty"`
}

type ResourceRef struct {
	Type      ResourceType
	Namespace string
	Name      string
	ID        string
	Key       string
}

type ResourceType string

type Resources struct {
	// CPU request in millicores (1000m = 1 CPU)
	CPU ResourceLimit `json:"cpu,omitempty" yaml:"cpu,omitempty"`

	// Memory request in bytes
	Memory ResourceLimit `json:"memory,omitempty" yaml:"memory,omitempty"`
}

type RestartPolicy string

type RetryPolicy struct {
	// Number of retry attempts
	Count int `json:"count" yaml:"count"`

	// Backoff type (fixed or exponential)
	Backoff string `json:"backoff" yaml:"backoff"`

	// Initial backoff duration in seconds (for fixed or exponential)
	BackoffSeconds int `json:"backoffSeconds,omitempty" yaml:"backoffSeconds,omitempty"`
}

type RotationAction struct {
	// Services to reload (send SIGHUP)
	ReloadServices []string `json:"reloadServices,omitempty" yaml:"reloadServices,omitempty"`

	// Services to restart (rolling restart)
	RestartServices []string `json:"restartServices,omitempty" yaml:"restartServices,omitempty"`

	// Job to run
	RunJob string `json:"runJob,omitempty" yaml:"runJob,omitempty"`
}

type RotationPolicy struct {
	// Interval between rotations (e.g., "30d", "90d")
	Interval string `json:"interval" yaml:"interval"`

	// Actions to take after rotation
	OnRotate []RotationAction `json:"onRotate,omitempty" yaml:"onRotate,omitempty"`
}

type Route struct {
	// Unique identifier for the route
	ID string `json:"id" yaml:"id"`

	// Human-readable name for the route
	Name string `json:"name" yaml:"name"`

	// Namespace the route belongs to
	Namespace string `json:"namespace" yaml:"namespace"`

	// Gateway this route is attached to
	Gateway string `json:"gateway" yaml:"gateway"`

	// Host or hosts this route matches (e.g., "api.example.com")
	Hosts []string `json:"hosts,omitempty" yaml:"hosts,omitempty"`

	// HTTP path-based routing rules
	HTTP []HTTPRoute `json:"http,omitempty" yaml:"http,omitempty"`

	// TCP routing rules (port-based)
	TCP []TCPRoute `json:"tcp,omitempty" yaml:"tcp,omitempty"`

	// Priority of this route (higher numbers take precedence)
	Priority int `json:"priority,omitempty" yaml:"priority,omitempty"`

	// Creation timestamp
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`

	// Last update timestamp
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
}

type RouteDestination struct {
	// Service name to route to
	Service string `json:"service" yaml:"service"`

	// Namespace of the service (optional, defaults to route's namespace)
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`

	// Port on the service to route to
	Port int `json:"port" yaml:"port"`

	// Weight for traffic splitting (0-100)
	Weight int `json:"weight,omitempty" yaml:"weight,omitempty"`

	// Subset of the service to route to (requires service to have defined subsets)
	Subset string `json:"subset,omitempty" yaml:"subset,omitempty"`
}

type RouteSpec struct {
	// Route metadata and rules
	Route struct {
		// Human-readable name for the route (required)
		Name string `json:"name" yaml:"name"`

		// Namespace the route belongs to (optional, defaults to "default")
		Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`

		// Gateway this route is attached to
		Gateway string `json:"gateway" yaml:"gateway"`

		// Host or hosts this route matches
		Hosts []string `json:"hosts,omitempty" yaml:"hosts,omitempty"`

		// HTTP path-based routing rules
		HTTP []HTTPRoute `json:"http,omitempty" yaml:"http,omitempty"`

		// TCP routing rules (port-based)
		TCP []TCPRoute `json:"tcp,omitempty" yaml:"tcp,omitempty"`

		// Priority of this route (higher numbers take precedence)
		Priority int `json:"priority,omitempty" yaml:"priority,omitempty"`
	} `json:"route" yaml:"route"`
}

type RunIf struct {
	// Type selects the predicate. Empty is treated as RunIfFreshVolume.
	Type RunIfType `json:"type,omitempty" yaml:"type,omitempty"`

	// Path is the absolute in-container path tested when
	// Type=fileMissing. Required iff Type=fileMissing.
	Path string `json:"path,omitempty" yaml:"path,omitempty"`

	// Volume optionally restricts a fileMissing check to one named
	// parent volume. When empty, any mounted parent volume that
	// contains the path counts.
	Volume string `json:"volume,omitempty" yaml:"volume,omitempty"`
}

type RunIfType string

type RuneFile struct {
	// Server configuration
	Server *ServerConfig `yaml:"server,omitempty"`

	// Data directory for persistent storage
	DataDir string `yaml:"data_dir,omitempty"`

	// Client configuration
	Client *ClientConfig `yaml:"client,omitempty"`

	// Docker runner configuration (including private registries)
	Docker *DockerConfig `yaml:"docker,omitempty"`

	// Default namespace
	Namespace string `yaml:"namespace,omitempty"`

	// Authentication configuration
	Auth *AuthConfig `yaml:"auth,omitempty"`

	// Resource limits and requests
	Resources *ResourceConfig `yaml:"resources,omitempty"`

	// Logging configuration
	Log *LogConfig `yaml:"log,omitempty"`

	// Secret encryption + limits configuration
	Secret *SecretConfig `yaml:"secret,omitempty"`

	// Top-level config-resource limits (RUNE-016)
	Config *ConfigResourceConfig `yaml:"config,omitempty"`

	// Plugin configuration
	Plugins *PluginConfig `yaml:"plugins,omitempty"`

	// Networking layer (RUNE-040..067)
	Networking *NetworkingConfig `yaml:"networking,omitempty"`

	// Telemetry / metrics
	Telemetry *TelemetryConfig `yaml:"telemetry,omitempty"`

	// Node placement (edge / worker / leader)
	Node *NodeConfig `yaml:"node,omitempty"`

	// Ingress (edge node terminating user traffic)
	Ingress *IngressConfig `yaml:"ingress,omitempty"`

	// ACME (Let's Encrypt) configuration
	ACME *ACMEConfig `yaml:"acme,omitempty"`

	// Storage drivers. Per-driver opaque config maps keyed
	// by registry name (e.g. "local", "local-host"). The shape of
	// each inner map is driver-specific; the loader keeps it as raw
	// `any` and hands it to the driver factory.
	Storage *StorageConfig `yaml:"storage,omitempty"`

	// FailedInstanceRetention bounds how long preserved Failed-instance
	// containers (tombstones) survive before the reconciler's retention
	// GC reaps them. Mirrors internal/config.FailedInstanceRetention.
	FailedInstanceRetention *FailedInstanceRetentionConfig `yaml:"failed_instance_retention,omitempty"`

	// UI configures the embedded web dashboard (RUNE-200). Mirrors
	// internal/config.UI.
	UI *UIConfig `yaml:"ui,omitempty"`

	// Observability configures the native observability subsystem
	// (RuneSight): the agent forwarder, the log store backend, and
	// retention. Mirrors internal/config.Observability. When absent or
	// disabled, runed forwards no logs and `rune logs` falls back to the
	// live ephemeral stream.
	Observability *ObservabilityConfig `yaml:"observability,omitempty"`
	// contains filtered or unexported fields
}

type RunesetContext struct {
	Namespace   string
	Mode        string
	ReleaseName string
	Runeset     RunesetManifest
}

type RunesetManifest struct {
	Name        string                 `yaml:"name"`
	Version     string                 `yaml:"version"`
	Description string                 `yaml:"description"`
	Namespace   string                 `yaml:"namespace"`
	Defaults    map[string]interface{} `yaml:"defaults"`
}

type RunesetSourceType string

type RunnerType string

type RuntimeType string

type SavedView struct {
	// Unique identifier.
	ID string `json:"id" yaml:"id"`

	// DNS-1123 cluster-unique name (doubles as the URL-safe slug).
	Name string `json:"name" yaml:"name"`

	// Description is optional free-text shown in the Saved Views list.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// LogQL is the saved query text (the Core-tier subset the ObserveService
	// parses). Stored verbatim; parsed/validated at save time so a view can
	// never hold an unparseable query.
	LogQL string `json:"logql" yaml:"logql"`

	// Range is the dashboard's relative time-range token ("15m", "1h", "24h",
	// ...). The Explorer resolves it to absolute start/end at load time so a
	// saved view is always "the last X", not a frozen window.
	Range string `json:"range,omitempty" yaml:"range,omitempty"`

	// Pinned views surface on the RuneSight home card and sort first.
	Pinned bool `json:"pinned,omitempty" yaml:"pinned,omitempty"`

	// CreatedBy attributes the view (auth principal name; informational).
	CreatedBy string `json:"createdBy,omitempty" yaml:"createdBy,omitempty"`

	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
}

type ScalingMode string

type ScalingOperation struct {
	// Unique identifier for the operation
	ID string `json:"id"`

	// Namespace the service belongs to
	Namespace string `json:"namespace"`

	// Name of the service being scaled
	ServiceName string `json:"service_name"`

	// Current scale when operation started
	CurrentScale int `json:"current_scale"`

	// Target scale to reach
	TargetScale int `json:"target_scale"`

	// Step size for gradual scaling
	StepSize int `json:"step_size"`

	// Interval between steps in seconds
	Interval int `json:"interval"`

	// Time the operation started
	StartTime time.Time `json:"start_time"`

	// Time the operation ended (if completed/failed/cancelled)
	EndTime time.Time `json:"end_time,omitempty"`

	// Current status of the operation
	Status ScalingOperationStatus `json:"status"`

	// Mode of scaling (immediate or gradual)
	Mode ScalingMode `json:"mode"`

	// Reason for failure/cancellation if applicable
	FailureReason string `json:"failure_reason,omitempty"`
}

type ScalingOperationMetadata struct {
	// Creation timestamp
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`

	// Last update timestamp
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
}

type ScalingOperationParams struct {
	// Current scale of the service
	CurrentScale int

	// Target scale to reach
	TargetScale int

	// Step size for gradual scaling
	StepSize int

	// Interval between steps in seconds
	IntervalSeconds int

	// Whether to use gradual scaling
	IsGradual bool
}

type ScalingOperationStatus string

type SeccompProfile struct {
	// Type selects the profile family. Empty is treated as "default".
	Type SeccompProfileType `json:"type,omitempty" yaml:"type,omitempty"`

	// LocalhostProfile is an absolute path to a JSON seccomp profile
	// on the runtime host. Required iff Type=localhost.
	LocalhostProfile string `json:"localhostProfile,omitempty" yaml:"localhostProfile,omitempty"`
}

type SeccompProfileType string

type Secret struct {
	// Unique identifier for the secret
	ID string `json:"id" yaml:"id"`

	// Human-readable name for the secret (DNS-1123 unique name within a namespace)
	Name string `json:"name" yaml:"name"`

	// Namespace the secret belongs to
	Namespace string `json:"namespace" yaml:"namespace"`

	// Type of secret (static or dynamic)
	Type string `json:"type" yaml:"type"`

	// Static data (encrypted at rest, only for static secrets)
	Data map[string]string `json:"-" yaml:"-"` // Not serialized, stored encrypted separately

	// DataKeys is the sorted list of keys present in Data. It is populated
	// by metadata-only API responses (Get, List) so callers can see the
	// shape of a secret without learning its values. Reveal responses
	// populate both Data and DataKeys.
	DataKeys []string `json:"dataKeys,omitempty" yaml:"dataKeys,omitempty"`

	// Engine configuration for dynamic secrets
	Engine *SecretEngine `json:"engine,omitempty" yaml:"engine,omitempty"`

	// Rotation configuration
	Rotation *RotationPolicy `json:"rotation,omitempty" yaml:"rotation,omitempty"`

	// Current version number
	Version int `json:"version" yaml:"version"`

	// Creation timestamp
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`

	// Last update timestamp
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`

	// Last rotation timestamp
	LastRotated *time.Time `json:"lastRotated,omitempty" yaml:"lastRotated,omitempty"`

	// OwnedBy is the system ownership stamp set when a runeset release manages
	// this secret. Distinct from user data; used for GC and drift detection.
	// See _docs/plugins/RUNESET_STATEFUL_RELEASES.md.
	OwnedBy *OwnedBy `json:"ownedBy,omitempty" yaml:"ownedBy,omitempty"`
}

type SecretConfig struct {
	Encryption *EncryptionConfig `yaml:"encryption,omitempty"`
	Limits     *LimitsConfig     `yaml:"limits,omitempty"`
}

type SecretEngine struct {
	// Name of the engine to use (references a SecretsEngine resource)
	Name string `json:"name" yaml:"name"`

	// Role or profile to use with the engine (engine-specific)
	Role string `json:"role,omitempty" yaml:"role,omitempty"`

	// Engine-specific configuration for this secret
	Config map[string]interface{} `json:"config,omitempty" yaml:"config,omitempty"`
}

type SecretMount struct {
	// Name of the mount (for identification)
	Name string `json:"name" yaml:"name"`

	// Path where the secret should be mounted
	MountPath string `json:"mountPath" yaml:"mountPath"`

	// Name of the secret to mount
	SecretName string `json:"secretName" yaml:"secretName"`

	// Optional: specific keys to project from the secret
	Items []KeyToPath `json:"items,omitempty" yaml:"items,omitempty"`
}

type SecretSpec struct {
	// Human-readable name for the secret (required)
	Name string `json:"name" yaml:"name"`

	// Namespace the secret belongs to (optional, defaults to "default")
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`

	// Type of secret (static or dynamic)
	Type string `json:"type" yaml:"type"`

	// Secret data for static secrets (only for creation, not returned in GET)
	Data map[string]string `json:"data,omitempty" yaml:"data,omitempty"`

	// Single value convenience field (alternative to data.value for simple secrets)
	Value string `json:"value,omitempty" yaml:"value,omitempty"`

	// Base64-encoded value (for binary data)
	ValueBase64 string `json:"valueBase64,omitempty" yaml:"valueBase64,omitempty"`

	// Engine configuration for dynamic secrets
	Engine *SecretEngine `json:"engine,omitempty" yaml:"engine,omitempty"`

	// Rotation configuration
	Rotation *RotationPolicy `json:"rotation,omitempty" yaml:"rotation,omitempty"`

	// Skip indicates this spec should be ignored by castfile parsing
	Skip bool `json:"skip,omitempty" yaml:"skip,omitempty"`
	// contains filtered or unexported fields
}

type SecretsEngine struct {
	// Unique identifier for the engine
	ID string `json:"id" yaml:"id"`

	// Human-readable name for the engine
	Name string `json:"name" yaml:"name"`

	// Namespace the engine belongs to
	Namespace string `json:"namespace" yaml:"namespace"`

	// Type of engine (builtin, function, plugin)
	Type string `json:"type" yaml:"type"`

	// For function-based engines, the reference to the function
	Function string `json:"function,omitempty" yaml:"function,omitempty"`

	// For plugin-based engines, the path to the plugin executable
	Path string `json:"path,omitempty" yaml:"path,omitempty"`

	// Engine-wide configuration
	Config map[string]interface{} `json:"config,omitempty" yaml:"config,omitempty"`

	// Creation timestamp
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`

	// Last update timestamp
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
}

type SecretsEngineSpec struct {
	// Engine metadata and configuration
	SecretsEngine struct {
		// Human-readable name for the engine (required)
		Name string `json:"name" yaml:"name"`

		// Namespace the engine belongs to (optional, defaults to "default")
		Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`

		// Type of engine (required: builtin, function, plugin)
		Type string `json:"type" yaml:"type"`

		// For function-based engines, the reference to the function
		Function string `json:"function,omitempty" yaml:"function,omitempty"`

		// For plugin-based engines, the path to the plugin executable
		Path string `json:"path,omitempty" yaml:"path,omitempty"`

		// Engine-wide configuration
		Config map[string]interface{} `json:"config,omitempty" yaml:"config,omitempty"`
	} `json:"secretsEngine" yaml:"secretsEngine"`
}

type SecurityContext struct {
	// SeccompProfile selects the seccomp policy applied to the
	// container. Nil means the runtime default profile.
	SeccompProfile *SeccompProfile `json:"seccompProfile,omitempty" yaml:"seccompProfile,omitempty"`

	// CapAdd are Linux capabilities granted to the container in
	// addition to the runtime defaults (e.g. "SYS_ADMIN", "NET_ADMIN").
	CapAdd []string `json:"capAdd,omitempty" yaml:"capAdd,omitempty"`

	// CapDrop are Linux capabilities removed from the container,
	// applied after CapAdd.
	CapDrop []string `json:"capDrop,omitempty" yaml:"capDrop,omitempty"`

	// Privileged grants full access to host devices and namespaces.
	// Admin-gated by the services.privileged policy verb.
	Privileged bool `json:"privileged,omitempty" yaml:"privileged,omitempty"`
}

type ServerConfig struct {
	GRPCAddress string     `yaml:"grpc_address,omitempty"`
	HTTPAddress string     `yaml:"http_address,omitempty"`
	TLS         *TLSConfig `yaml:"tls,omitempty"`
}

type Service struct {
	NamespacedResource `json:"-" yaml:"-"`

	// Unique identifier for the service
	ID string `json:"id" yaml:"id"`

	// Human-readable name for the service // DNS-1123 unique name within a namespace
	Name string `json:"name" yaml:"name"`

	// Namespace the service belongs to
	Namespace string `json:"namespace" yaml:"namespace"`

	// Labels are key/value pairs that can be used to organize and categorize services
	Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`

	// Container image for the service
	Image string `json:"image,omitempty" yaml:"image,omitempty"`

	// Named registry selector for pulling the image (optional)
	ImageRegistry string `json:"imageRegistry,omitempty" yaml:"imageRegistry,omitempty"`

	// Registry override allowing inline auth or named selection (optional)
	Registry *ServiceRegistryOverride `json:"registry,omitempty" yaml:"registry,omitempty"`

	// ImagePull controls when the runner pulls the container image.
	// Allowed values: "always", "missing", "never". Empty defaults to
	// "always" (re-pull on every deploy/restart).
	ImagePull string `json:"imagePull,omitempty" yaml:"imagePull,omitempty"`

	// Command to run in the container (overrides image CMD)
	Command string `json:"command,omitempty" yaml:"command,omitempty"`

	// Arguments to the command
	Args []string `json:"args,omitempty" yaml:"args,omitempty"`

	// Environment variables for the service
	Env map[string]string `json:"env,omitempty" yaml:"env,omitempty"`

	// Imported environment variables sources (normalized from spec)
	EnvFrom []EnvFromSource `json:"envFrom,omitempty" yaml:"envFrom,omitempty"`

	// Number of instances to run
	Scale int `json:"scale" yaml:"scale"`

	// Ports exposed by the service
	Ports []ServicePort `json:"ports,omitempty" yaml:"ports,omitempty"`

	// Resource requirements for each instance
	Resources Resources `json:"resources,omitempty" yaml:"resources,omitempty"`

	// Health checks for the service
	Health *HealthCheck `json:"health,omitempty" yaml:"health,omitempty"`

	// Network policy for controlling traffic
	NetworkPolicy *ServiceNetworkPolicy `json:"networkPolicy,omitempty" yaml:"networkPolicy,omitempty"`

	// External exposure configuration
	Expose *ServiceExpose `json:"expose,omitempty" yaml:"expose,omitempty"`

	// Placement preferences and requirements
	Affinity *ServiceAffinity `json:"affinity,omitempty" yaml:"affinity,omitempty"`

	// Autoscaling configuration
	Autoscale *ServiceAutoscale `json:"autoscale,omitempty" yaml:"autoscale,omitempty"`

	// Secret mounts
	SecretMounts []SecretMount `json:"secretMounts,omitempty" yaml:"secretMounts,omitempty"`

	// Config mounts
	ConfigmapMounts []ConfigmapMount `json:"configmapMounts,omitempty" yaml:"configmapMounts,omitempty"`

	// Volume mounts. Each entry references either a pre-existing
	// VolumeClaim by name (Claim) or an inline ClaimTemplate that the
	// VolumeController materializes into a per-instance Volume.
	Volumes []VolumeMount `json:"volumes,omitempty" yaml:"volumes,omitempty"`

	// InitSteps run sequentially before each instance's main
	// container starts. They share the parent's volumes / secret /
	// config / env by default. See RUNE-121.
	InitSteps []InitStep `json:"initSteps,omitempty" yaml:"initSteps,omitempty"`

	// SecurityContext applied to the main container. Privileged=true
	// and seccompProfile.type=unconfined are gated server-side behind
	// the services.privileged policy verb.
	SecurityContext *SecurityContext `json:"securityContext,omitempty" yaml:"securityContext,omitempty"`

	// Service discovery configuration
	Discovery *ServiceDiscovery `json:"discovery,omitempty" yaml:"discovery,omitempty"`

	// Dependencies this service declares (normalized internal form)
	Dependencies []DependencyRef `json:"dependencies,omitempty" yaml:"dependencies,omitempty"`

	// Status of the service
	Status ServiceStatus `json:"status" yaml:"status"`

	// StatusReason is a short, machine-friendly slug describing why
	// the service is in its current Status. Set by the reconciler when
	// rolling up the worst instance state. Examples: "ImageUnreachable",
	// "Unhealthy", "OutOfMemory", "Unplaceable", "ConfigMissing".
	// Empty when Status is Running.
	StatusReason string `json:"statusReason,omitempty" yaml:"statusReason,omitempty"`

	// StatusMessage is a single human-readable sentence explaining
	// StatusReason, copied verbatim from the worst instance's
	// StatusMessage. The CLI shows this directly on `rune get
	// service <name>` and on cast failure so developers never have to
	// run a second command to learn why a service is unhealthy.
	StatusMessage string `json:"statusMessage,omitempty" yaml:"statusMessage,omitempty"`

	// IngressCert tracks asynchronous TLS certificate state for the
	// ingress controller (RUNE-066). Populated only when Expose is
	// configured for ACME-managed TLS. The orchestrator updates this
	// field independently of cast; cast does not block on issuance.
	IngressCert *IngressCertStatus `json:"ingressCert,omitempty" yaml:"ingressCert,omitempty"`

	// Instances of this service currently running
	Instances []Instance `json:"instances,omitempty" yaml:"instances,omitempty"`

	// Runtime for the service ("container" or "process")
	Runtime RuntimeType `json:"runtime,omitempty" yaml:"runtime,omitempty"`

	// Process-specific configuration (when Runtime="process")
	Process *ProcessSpec `json:"process,omitempty" yaml:"process,omitempty"`

	// Restart policy for the service
	RestartPolicy RestartPolicy `json:"restart_policy,omitempty" yaml:"restart_policy,omitempty"`

	// Metadata for the service
	Metadata *ServiceMetadata `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

type ServiceAffinity struct {
	// Hard constraints (service can only run on nodes matching these)
	Required []string `json:"required,omitempty" yaml:"required,omitempty"`

	// Soft preferences (scheduler will try to place on nodes matching these)
	Preferred []string `json:"preferred,omitempty" yaml:"preferred,omitempty"`

	// Run instances near services matching these labels
	With []string `json:"with,omitempty" yaml:"with,omitempty"`

	// Avoid running instances on nodes with services matching these labels
	Avoid []string `json:"avoid,omitempty" yaml:"avoid,omitempty"`

	// Try to distribute instances across this topology key (e.g., "zone")
	Spread string `json:"spread,omitempty" yaml:"spread,omitempty"`
}

type ServiceAutoscale struct {
	// Whether autoscaling is enabled
	Enabled bool `json:"enabled" yaml:"enabled"`

	// Minimum number of instances
	Min int `json:"min" yaml:"min"`

	// Maximum number of instances
	Max int `json:"max" yaml:"max"`

	// Metric to scale on (e.g., cpu, memory)
	Metric string `json:"metric" yaml:"metric"`

	// Target value for the metric (e.g., 70%)
	Target string `json:"target" yaml:"target"`

	// Cooldown period between scaling events
	Cooldown string `json:"cooldown,omitempty" yaml:"cooldown,omitempty"`

	// Maximum number of instances to add/remove in a single scaling event
	Step int `json:"step,omitempty" yaml:"step,omitempty"`
}

type ServiceDependency struct {
	// Optional raw FQDN captured by YAML parsing helpers
	FQDN string `json:"-" yaml:"-"`

	Service   string `json:"service,omitempty" yaml:"service,omitempty"`
	Secret    string `json:"secret,omitempty" yaml:"secret,omitempty"`
	Configmap string `json:"configmap,omitempty" yaml:"configmap,omitempty"`
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
}

type ServiceDiscovery struct {
	// Discovery mode (load-balanced or headless)
	Mode string `json:"mode,omitempty" yaml:"mode,omitempty"`

	// VIP is the cluster virtual IP allocated for this service. Set by
	// the control plane on Create via the cluster VIP allocator
	// (RUNE-040). Stable for the lifetime of the service ID.
	VIP string `json:"vip,omitempty" yaml:"vip,omitempty"`

	// LocalityPreference controls how the userspace proxy picks
	// endpoints (RUNE-041). One of "" (no preference), "prefer-local"
	// (same-node first, fall back to remote), or "local-only" (fail
	// closed if no local endpoint).
	LocalityPreference string `json:"localityPreference,omitempty" yaml:"localityPreference,omitempty"`
}

type ServiceDiscoverySpec struct {
	Mode               string `json:"mode,omitempty" yaml:"mode,omitempty"`
	LocalityPreference string `json:"localityPreference,omitempty" yaml:"localityPreference,omitempty"`
}

type ServiceEndpoints struct {
	// Service full name (namespace.name)
	ServiceID string `json:"serviceId" yaml:"serviceId"`

	// Individual endpoints (instances) for this service
	Endpoints []Endpoint `json:"endpoints" yaml:"endpoints"`

	// Service-level metadata
	Metadata map[string]string `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

type ServiceExpose struct {
	// Port or port name to expose
	Port string `json:"port" yaml:"port"`

	// Host for the exposed service
	Host string `json:"host,omitempty" yaml:"host,omitempty"`

	// Path prefix for the exposed service
	Path string `json:"path,omitempty" yaml:"path,omitempty"`

	// TLS configuration for the exposed service
	TLS *ExposeServiceTLS `json:"tls,omitempty" yaml:"tls,omitempty"`

	// AllowCIDRs restricts inbound connections to these source CIDRs,
	// enforced at the ingress listener against the real TCP peer (not a
	// forwarding header). Empty means "no restriction" (allow all) — never
	// deny-all. Defense-in-depth for origin lockdown behind a CDN. Only
	// meaningful when ingress is the direct TCP terminator (no L4 LB in
	// front rewriting the source IP).
	AllowCIDRs []string `json:"allowCidrs,omitempty" yaml:"allowCidrs,omitempty"`

	// ClientCert requires a trusted client certificate (mTLS) on inbound
	// TLS connections, verified at the ingress handshake. The primary
	// origin-lockdown control — strongest when the CA is account-specific
	// (not a CDN's shared origin-pull CA).
	ClientCert *ExposeClientCert `json:"clientCert,omitempty" yaml:"clientCert,omitempty"`
}

type ServiceFinalizerInterface interface {
	DeleteService(ctx context.Context, service *Service) error
}

type ServiceMetadata struct {
	// Creation timestamp
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`

	// Last update timestamp
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`

	// Generation of the service
	Generation int64 `json:"generation,omitempty" yaml:"generation,omitempty"`

	// TemplateGeneration tracks changes to the instance TEMPLATE — the parts
	// of the spec that define what a container looks like (image, env, mounts,
	// ports, ...) — as opposed to Generation, which advances on EVERY
	// desired-state change including scale. Cast bumps both (to the same
	// value); the scaling controller bumps only Generation. Instances record
	// TemplateGeneration at creation, and the compatibility check compares
	// against it — so a scale-up never recreates surviving containers, while
	// a spec change still does (issue #142; mirrors the K8s
	// Deployment-generation vs pod-template-hash split). Pre-existing services
	// have 0 here, which compares as "not newer than any instance" until the
	// next cast stamps it.
	TemplateGeneration int64 `json:"templateGeneration,omitempty" yaml:"templateGeneration,omitempty"`

	// ObservedGeneration is the Generation the reconciler last acted on. When it
	// equals Generation, the desired state (spec + scale) is fully reconciled, so
	// an incoming update carries only status/observed fields and reconciliation
	// can be skipped (see serviceController.isStatusOnlyChange). Every
	// desired-state change bumps Generation — including scale, which the scaling
	// controller now increments — so this single persisted field replaces the
	// in-memory serviceObservedGenerations/serviceObservedScales shadow maps and,
	// unlike them, survives a runed restart (RFC #129 Phase 2).
	ObservedGeneration int64 `json:"observedGeneration,omitempty" yaml:"observedGeneration,omitempty"`

	// OwnedBy is the system ownership stamp set when a runeset release manages
	// this service. See _docs/plugins/RUNESET_STATEFUL_RELEASES.md.
	OwnedBy *OwnedBy `json:"ownedBy,omitempty" yaml:"ownedBy,omitempty"`

	// LastNonZeroScale tracks the most recent non-zero scale to support restart semantics
	LastNonZeroScale int `json:"lastNonZeroScale,omitempty" yaml:"lastNonZeroScale,omitempty"`

	// DeletionTimestamp marks the service as being torn down (Kubernetes-style
	// foreground deletion, RFC #129 Phase 4). Once set, the reconciler drives
	// reconcileDeletion instead of reconciling toward the spec, and the record
	// is NOT removed from the store until every finalizer has cleared. Being
	// persisted, an interrupted teardown resumes on the next reconcile with no
	// separate recovery path.
	DeletionTimestamp *time.Time `json:"deletionTimestamp,omitempty" yaml:"deletionTimestamp,omitempty"`

	// Finalizers are the ordered cleanup steps that must complete before the
	// service record may be removed. Populated when DeletionTimestamp is set
	// (instance-cleanup, then volume-cleanup iff the service has claimTemplate
	// volumes). The reconciler pops each entry only after its work is fully
	// done; when the list is empty the record is deleted (the terminal
	// transition). This gate is what makes the record provably outlive its
	// instances and volumes — orphans become impossible by construction.
	Finalizers []FinalizerType `json:"finalizers,omitempty" yaml:"finalizers,omitempty"`
}

type ServiceNetworkPolicy struct {
	// Ingress rules (traffic coming into the service)
	Ingress []IngressRule `json:"ingress,omitempty" yaml:"ingress,omitempty"`

	// Egress rules (traffic going out from the service)
	Egress []EgressRule `json:"egress,omitempty" yaml:"egress,omitempty"`
}

type ServicePort struct {
	// Name for this port (used in references)
	Name string `json:"name" yaml:"name"`

	// Port number
	Port int `json:"port" yaml:"port"`

	// Target port (if different from port)
	TargetPort int `json:"targetPort,omitempty" yaml:"targetPort,omitempty"`

	// Protocol (default: TCP)
	Protocol string `json:"protocol,omitempty" yaml:"protocol,omitempty"`

	// HostPort, when > 0, publishes the container's port to the host on
	// 127.0.0.1:<HostPort>. Intended as a dev-mode escape hatch on
	// platforms where the cluster dataplane cannot reach the container
	// bridge IP from the host (notably macOS Docker Desktop). Production
	// services should reach services through the cluster VIP or ingress,
	// not via a published host port.
	HostPort int `json:"hostPort,omitempty" yaml:"hostPort,omitempty"`
}

type ServiceRegistry struct {
	// Map of service namespaced names to endpoint information
	Services map[string]*ServiceEndpoints `json:"services" yaml:"services"`

	// Last update timestamp
	LastUpdated time.Time `json:"lastUpdated" yaml:"lastUpdated"`
}

type ServiceRegistryOverride struct {
	Name string        `json:"name,omitempty" yaml:"name,omitempty"`
	Auth *RegistryAuth `json:"auth,omitempty" yaml:"auth,omitempty"`
}

type ServiceSpec struct {
	// Human-readable name for the service (required)
	Name string `json:"name" yaml:"name"`

	// Namespace the service belongs to (optional, defaults to "default")
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`

	// Labels for the service
	Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`

	// Container image for the service (required)
	Image string `json:"image" yaml:"image"`

	// Command to run in the container (overrides image CMD)
	Command string `json:"command,omitempty" yaml:"command,omitempty"`

	// Arguments to the command
	Args []string `json:"args,omitempty" yaml:"args,omitempty"`

	// Environment variables for the service
	Env map[string]string `json:"env,omitempty" yaml:"env,omitempty"`

	// Import environment variables from secrets/configmaps with optional prefix
	EnvFrom EnvFromList `json:"envFrom,omitempty" yaml:"envFrom,omitempty"`

	// Number of instances to run (default: 1)
	Scale int `json:"scale" yaml:"scale"`

	// Ports exposed by the service
	Ports []ServicePort `json:"ports,omitempty" yaml:"ports,omitempty"`

	// Resource requirements for each instance
	Resources *Resources `json:"resources,omitempty" yaml:"resources,omitempty"`

	// Health checks for the service
	Health *HealthCheck `json:"health,omitempty" yaml:"health,omitempty"`

	// Network policy for controlling traffic
	NetworkPolicy *ServiceNetworkPolicy `json:"networkPolicy,omitempty" yaml:"networkPolicy,omitempty"`

	// External exposure configuration
	Expose *ServiceExpose `json:"expose,omitempty" yaml:"expose,omitempty"`

	// Placement preferences and requirements
	Affinity *ServiceAffinity `json:"affinity,omitempty" yaml:"affinity,omitempty"`

	// Autoscaling configuration
	Autoscale *ServiceAutoscale `json:"autoscale,omitempty" yaml:"autoscale,omitempty"`

	// Secret mounts
	SecretMounts []SecretMount `json:"secretMounts,omitempty" yaml:"secretMounts,omitempty"`

	// Configmap mounts
	ConfigmapMounts []ConfigmapMount `json:"configmapMounts,omitempty" yaml:"configmapMounts,omitempty"`

	// Volume mounts. Each entry references either a pre-existing Volume by
	// name (Claim) or an inline ClaimTemplate the controller materializes
	// into a per-instance Volume.
	Volumes []VolumeMount `json:"volumes,omitempty" yaml:"volumes,omitempty"`

	// Service discovery configuration (operator-facing; no VIP field).
	Discovery *ServiceDiscoverySpec `json:"discovery,omitempty" yaml:"discovery,omitempty"`

	// Named registry selector for pulling the image (optional)
	ImageRegistry string `json:"imageRegistry,omitempty" yaml:"imageRegistry,omitempty"`

	// Registry override allowing inline auth or named selection (optional)
	Registry *ServiceRegistryOverride `json:"registry,omitempty" yaml:"registry,omitempty"`

	// ImagePull controls when the runner pulls the container image.
	// Allowed values: "always" (default), "missing", "never".
	ImagePull string `json:"imagePull,omitempty" yaml:"imagePull,omitempty"`

	// Skip indicates this spec should be ignored by castfile parsing
	Skip bool `json:"skip,omitempty" yaml:"skip,omitempty"`

	// Dependencies in user-facing form. Accepts either:
	// - FQDN strings (e.g., "db.prod.rune") as YAML sequence entries
	// - ResourceRef strings (e.g., "secret:db-creds" or "configmap:app-settings")
	// - Structured objects (service/secret/configmap with optional namespace)
	// These will be normalized to []DependencyRef in internal Service
	Dependencies []ServiceDependency `json:"dependencies,omitempty" yaml:"dependencies,omitempty"`

	// InitSteps run sequentially before each instance's main container (RUNE-121).
	InitSteps []InitStep `json:"initSteps,omitempty" yaml:"initSteps,omitempty"`

	// SecurityContext applied to the main container. Privileged and
	// seccomp=unconfined are admin-gated by the server.
	SecurityContext *SecurityContext `json:"securityContext,omitempty" yaml:"securityContext,omitempty"`
	// contains filtered or unexported fields
}

type ServiceStatus string

type ServiceStatusInfo struct {
	Status ServiceStatus

	// ObservedGeneration tracks which generation was last processed by the controller
	ObservedGeneration int64 `json:"observedGeneration,omitempty" yaml:"observedGeneration,omitempty"`

	// DesiredInstances is the number of instances that should be running
	DesiredInstances int

	// RunningInstances is the number of instances that are currently running
	RunningInstances int
}

type Snapshot struct {
	NamespacedResource `json:"-" yaml:"-"`

	ID        string            `json:"id" yaml:"id"`
	Name      string            `json:"name" yaml:"name"`
	Namespace string            `json:"namespace" yaml:"namespace"`
	Labels    map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`

	// SourceVolume is the bare name of the Volume in the same namespace
	// (cross-namespace snapshots are out of scope).
	SourceVolume string `json:"sourceVolume" yaml:"sourceVolume"`

	// Driver records which driver took the snapshot — needed at restore
	// time to route the call.
	Driver string `json:"driver" yaml:"driver"`

	// Handle is the driver-populated opaque snapshot identifier.
	Handle string `json:"handle,omitempty" yaml:"handle,omitempty"`

	// SizeBytes is the apparent size of the captured data.
	SizeBytes int64 `json:"sizeBytes,omitempty" yaml:"sizeBytes,omitempty"`

	// Scheduled is true if the snapshot was created by a SnapshotSchedule
	// rather than an explicit `rune snapshot create` call. Retention reaping
	// only considers scheduled snapshots.
	Scheduled bool `json:"scheduled,omitempty" yaml:"scheduled,omitempty"`

	Phase   SnapshotPhase `json:"phase" yaml:"phase"`
	Reason  string        `json:"reason,omitempty" yaml:"reason,omitempty"`
	Message string        `json:"message,omitempty" yaml:"message,omitempty"`

	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
}

type SnapshotPhase string

type SnapshotSchedule struct {
	// Cron expression in standard 5-field format ("0 2 * * *").
	Cron string `json:"cron" yaml:"cron"`

	// Retention is the number of historical snapshots to keep. Older
	// snapshots are reaped after each successful new snapshot.
	Retention int `json:"retention,omitempty" yaml:"retention,omitempty"`
}

type Spec interface {
	// Validate ensures the spec is structurally and semantically valid.
	Validate() error
	// GetName returns the resource name declared in the spec.
	GetName() string
	// GetNamespace returns the resource namespace declared in the spec
	// (defaulting behavior may be applied by callers as needed).
	GetNamespace() string
	// Kind returns the logical resource kind (e.g., "Service", "Secret", "Config").
	Kind() string
}

type StorageClass struct {
	// Unique identifier for the storage class.
	ID string `json:"id" yaml:"id"`

	// DNS-1123 cluster-unique name.
	Name string `json:"name" yaml:"name"`

	// Driver is the registered driver name (e.g. "local", "local-host",
	// "do-volume", "aws-ebs"). Resolved against the storage driver registry
	// at controller boot — unknown drivers fail validation.
	Driver string `json:"driver" yaml:"driver"`

	// Parameters are driver-specific key/value settings (filesystem type,
	// IOPS, region, etc.). Volume.Parameters override these per-volume.
	Parameters map[string]string `json:"parameters,omitempty" yaml:"parameters,omitempty"`

	// ReclaimPolicy is the default reclaim policy inherited by child
	// volumes. Volume.ReclaimPolicy overrides it.
	ReclaimPolicy ReclaimPolicy `json:"reclaimPolicy,omitempty" yaml:"reclaimPolicy,omitempty"`

	// AllowedTopologies constrains both provisioning and instance placement.
	// An empty slice means no topology restriction.
	AllowedTopologies []TopologySelector `json:"allowedTopologies,omitempty" yaml:"allowedTopologies,omitempty"`

	// Default indicates this is the cluster-default class. The API server
	// enforces an at-most-one invariant — setting Default: true on a second
	// class atomically clears the previous default. claimTemplate without an
	// explicit storageClassName resolves to whichever class currently has
	// Default: true.
	Default bool `json:"default,omitempty" yaml:"default,omitempty"`

	// Labels attached to the storage class.
	Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`

	// Creation timestamp.
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`

	// Last update timestamp.
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
}

type StorageConfig struct {
	// DefaultStorageClass — see internal/config.Storage.DefaultStorageClass.
	DefaultStorageClass *string `yaml:"defaultStorageClass,omitempty"`

	// PreserveOnDelete — see internal/config.Storage.PreserveOnDelete.
	PreserveOnDelete bool `yaml:"preserveOnDelete,omitempty"`

	// AllowCreateMissing — see internal/config.Storage.AllowCreateMissing.
	AllowCreateMissing bool `yaml:"allowCreateMissing,omitempty"`

	Drivers map[string]map[string]any `yaml:"drivers,omitempty"`
}

type StoredSecret struct {
	// Name of the secret
	Name string `json:"name"`

	// Namespace of the secret
	Namespace string `json:"namespace"`

	// Version of the secret
	Version int `json:"version"`

	// Creation timestamp
	CreatedAt time.Time `json:"createdAt"`

	// Last update timestamp
	UpdatedAt time.Time `json:"updatedAt"`

	// Ciphertext of the secret
	Ciphertext []byte `json:"ciphertext"`

	// Wrapped DEK of the secret
	WrappedDEK []byte `json:"wrappedDEK"`

	// OwnedBy is the system ownership stamp. It is plaintext metadata (NOT part
	// of the encrypted payload) so a runeset release's ownership of a secret
	// survives storage and is visible to drift/adoption checks. Round-tripped by
	// encryptSecret/decryptSecret. See RUNESET_STATEFUL_RELEASES.md.
	OwnedBy *OwnedBy `json:"ownedBy,omitempty"`
}

type TCPRoute struct {
	// Port number for this TCP route
	Port int `json:"port" yaml:"port"`

	// Destination service and options
	Destination RouteDestination `json:"destination" yaml:"destination"`
}

type TLSConfig struct {
	Enabled  bool   `yaml:"enabled"`
	CertFile string `yaml:"cert_file,omitempty"`
	KeyFile  string `yaml:"key_file,omitempty"`
}

type TelemetryConfig struct {
	MetricsAddr string `yaml:"metrics_addr,omitempty"`
}

type Token struct {
	ID          string     `json:"id" yaml:"id"`
	Name        string     `json:"name" yaml:"name"`
	SubjectID   string     `json:"subjectId" yaml:"subjectId"`
	SubjectType string     `json:"subjectType" yaml:"subjectType"` // "user" | "service"
	Description string     `json:"description,omitempty" yaml:"description,omitempty"`
	IssuedAt    time.Time  `json:"issuedAt" yaml:"issuedAt"`
	ExpiresAt   *time.Time `json:"expiresAt,omitempty" yaml:"expiresAt,omitempty"`
	Revoked     bool       `json:"revoked" yaml:"revoked"`
	SecretHash  string     `json:"secretHash" yaml:"secretHash"`

	// Kind discriminates static/access/refresh (RUNE-201).
	Kind TokenKind `json:"kind,omitempty" yaml:"kind,omitempty"`

	// PrevSecretHash holds the hash of the immediately-prior refresh secret for
	// a refresh grant, set on rotation. It exists so a genuinely stale (post
	// grace-window) reuse of a rotated refresh secret can be identified and
	// treated as theft. Only meaningful when Kind==refresh.
	PrevSecretHash string `json:"prevSecretHash,omitempty" yaml:"prevSecretHash,omitempty"`

	// LastUsedAt records the last time a refresh grant was rotated (RUNE-201
	// sliding expiry). Only meaningful when Kind==refresh.
	LastUsedAt *time.Time `json:"lastUsedAt,omitempty" yaml:"lastUsedAt,omitempty"`
}

type TokenKind string

type TopologyMatchExpression struct {
	// Key is the label name (e.g. "rune.io/zone").
	Key string `json:"key" yaml:"key"`

	// Operator is one of: In, NotIn, Exists, DoesNotExist.
	Operator TopologyOperator `json:"operator" yaml:"operator"`

	// Values is the set of allowed/disallowed values. Required for In/NotIn,
	// must be empty for Exists/DoesNotExist.
	Values []string `json:"values,omitempty" yaml:"values,omitempty"`
}

type TopologyOperator string

type TopologySelector struct {
	// MatchLabels is a map of {key: value} pairs. All pairs must match.
	MatchLabels map[string]string `json:"matchLabels,omitempty" yaml:"matchLabels,omitempty"`

	// MatchExpressions allows expressing set-based requirements (e.g.
	// "key rune.io/zone In [us-east-1a, us-east-1b]"). Use this when a
	// single class needs to span multiple zones — duplicate keys in
	// MatchLabels would silently collapse to the last value.
	MatchExpressions []TopologyMatchExpression `json:"matchExpressions,omitempty" yaml:"matchExpressions,omitempty"`
}

type UIConfig struct {
	// Enabled turns the dashboard (and the HTTP serving layer) on/off.
	Enabled bool `yaml:"enabled,omitempty"`
	// Path is the dashboard mount point (default /ui).
	Path string `yaml:"path,omitempty"`
	// HandoffEnabled allows the `rune ui` token-handoff flow.
	HandoffEnabled bool `yaml:"handoff_enabled,omitempty"`
	// HandoffTTL bounds a one-time handoff code's lifetime.
	HandoffTTL time.Duration `yaml:"handoff_ttl,omitempty"`
	// RequireTLS refuses to serve the UI over plaintext on a non-loopback
	// address (binds 127.0.0.1 only when TLS is off).
	RequireTLS bool `yaml:"require_tls,omitempty"`
}

type User struct {
	ID        string    `json:"id" yaml:"id"`
	Name      string    `json:"name" yaml:"name"`
	Email     string    `json:"email,omitempty" yaml:"email,omitempty"`
	Policies  []string  `json:"policies,omitempty" yaml:"policies,omitempty"`
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`
}