v1alpha1

type ConfigMapKeyRef struct {
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name"`
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Key string `json:"key"`
}

type ConfigMapVolumeSource struct {
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name"`
	// Items selects keys and their file paths. Unset projects every key as
	// a file named after it.
	// +optional
	// +kubebuilder:validation:MaxItems=64
	Items []KeyToPath `json:"items,omitempty"`
}

type Container struct {
	// Name is the container name, unique within the pod. It must not equal
	// the workload's own name, which the main container uses.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
	Name string `json:"name"`

	// Image is the sidecar's image, typically third-party
	// (gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.14.1).
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=500
	Image string `json:"image"`

	// Command overrides the image's entrypoint.
	// +optional
	// +kubebuilder:validation:MaxItems=64
	// +kubebuilder:validation:items:MaxLength=4096
	Command []string `json:"command,omitempty"`

	// Args are the entrypoint's arguments.
	// +optional
	// +kubebuilder:validation:MaxItems=64
	// +kubebuilder:validation:items:MaxLength=4096
	Args []string `json:"args,omitempty"`

	// Env is the sidecar's environment. Like WorkloadSpec.Env, it has no
	// portable entry-count limit; exec byte limits depend on resolved values.
	// +optional
	// +listType=map
	// +listMapKey=name
	Env []EnvVar `json:"env,omitempty"`

	// Ports are the sidecar's container ports.
	// +optional
	// +listType=map
	// +listMapKey=name
	// +kubebuilder:validation:MaxItems=16
	Ports []Port `json:"ports,omitempty"`

	// Resources is the sidecar's compute request and limit, with the same
	// defaults as the main container.
	// +optional
	Resources Resources `json:"resources,omitempty"`

	// Probes are the sidecar's own probes. Unset means none: unlike a
	// service, a sidecar gets no implicit TCP probe.
	// +optional
	Probes *Probes `json:"probes,omitempty"`

	// Native renders the sidecar as a Kubernetes native sidecar: an
	// initContainer with restartPolicy Always (GA in Kubernetes 1.29). The
	// kubelet starts it BEFORE the main container and waits for its startup
	// probe to pass, and stops it AFTER the main container exits. A plain
	// sidecar starts concurrently with the main container, so a main
	// process that dials the sidecar at boot (a database proxy on
	// 127.0.0.1) races it and fails until the sidecar is listening. Set
	// Probes.StartupPath so "started" means "ready to serve"; without a
	// startup probe the kubelet only waits for the process to launch.
	// +optional
	Native bool `json:"native,omitempty"`
}

type DatabaseBackupStatus struct {
	// LastSuccessfulAt is when the last base backup completed. Nil means
	// none ever has.
	// +optional
	LastSuccessfulAt *metav1.Time `json:"lastSuccessfulAt,omitempty"`

	// WALArchivingHealthy is whether WAL is currently reaching the object
	// store. THIS IS THE SILENT FAILURE: a database whose archiving has
	// stopped keeps serving traffic normally, and every minute it does is a
	// minute that cannot be recovered to.
	// +optional
	WALArchivingHealthy bool `json:"walArchivingHealthy,omitempty"`

	// EarliestRestorableAt is the oldest point recovery can reach — the
	// floor set by the retention policy. Nil until a first backup exists.
	// +optional
	EarliestRestorableAt *metav1.Time `json:"earliestRestorableAt,omitempty"`

	// LastError is the last archiving or backup error, cleared on success.
	// It is surfaced verbatim: someone who can see "no bucket permission"
	// fixes it, while someone who sees only a false boolean files a ticket.
	// +optional
	LastError string `json:"lastError,omitempty"`
}

type DatabaseCredentialKey string

type DatabaseDashboards struct {
	// Enabled lets the dashboard role log in. False renders it NOLOGIN.
	// +optional
	Enabled bool `json:"enabled,omitempty"`

	// RowCap is the most rows one panel query returns.
	// +optional
	// +kubebuilder:default=1000
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=10000
	RowCap int32 `json:"rowCap,omitempty"`

	// TimeoutMs is the statement timeout of one panel query, in
	// milliseconds.
	// +optional
	// +kubebuilder:default=5000
	// +kubebuilder:validation:Minimum=100
	// +kubebuilder:validation:Maximum=10000
	TimeoutMs int32 `json:"timeoutMs,omitempty"`

	// MaxConcurrency is how many panel queries run at once. The role's
	// connection limit is one more than this, so a query that is being
	// cancelled never starves the next.
	// +optional
	// +kubebuilder:default=2
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=4
	MaxConcurrency int32 `json:"maxConcurrency,omitempty"`
}

type DatabaseRef struct {
	// Name is the ManagedDatabase's name.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=40
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
	Name string `json:"name"`
	// Key is the credential part. Empty means uri.
	// +optional
	Key DatabaseCredentialKey `json:"key,omitempty"`
}

type DatabaseRestore struct {
	// SourceDatabase is the ManagedDatabase whose backups are read. It may
	// be this database's own name (recreating it in place) or another in
	// the same environment — never one in another environment, which the
	// platform enforces by scoping the object-store prefix, not by
	// checking a string here.
	// +kubebuilder:validation:MinLength=1
	SourceDatabase string `json:"sourceDatabase"`

	// PointInTime stops recovery at an RFC3339 timestamp instead of
	// replaying every archived WAL. Unset recovers as far as the archive
	// goes.
	//
	// This is the field that makes the difference between "we have
	// backups" and "we can undo what happened at 14:05", and it is the
	// only reason continuous WAL archiving is worth its cost.
	// +optional
	PointInTime string `json:"pointInTime,omitempty"`
}

type DeletionPolicy string

type DeployPhase string

type DeploymentStrategy string

type EmptyDirVolumeSource struct {
	// SizeLimitBytes caps the volume. Unset means no cap beyond the node's
	// ephemeral storage.
	// +optional
	// +kubebuilder:validation:Minimum=1
	SizeLimitBytes int64 `json:"sizeLimitBytes,omitempty"`
}

type Engine string

type EnvVar struct {
	// Name is the variable name.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern=`^[A-Za-z_][A-Za-z0-9_]*$`
	Name string `json:"name"`

	// Value is an inline literal.
	// +optional
	// +kubebuilder:validation:MaxLength=32768
	Value string `json:"value,omitempty"`

	// SecretRef projects one key of a Secret in the workload's namespace.
	// +optional
	SecretRef *SecretKeyRef `json:"secretRef,omitempty"`

	// ManagedSecret names a value in the environment's secret store, and
	// whether its absence is tolerated.
	// +optional
	ManagedSecret *ManagedSecretRef `json:"managedSecret,omitempty"`

	// DatabaseRef projects a ManagedDatabase's credential.
	// +optional
	DatabaseRef *DatabaseRef `json:"databaseRef,omitempty"`

	// WorkloadURL is the public URL of another workload in the SAME
	// environment — the canonical case is a backend's CORS_ORIGINS naming
	// the StaticSite that calls it. It names a workload, never a hostname,
	// so it follows the workload when its URL changes.
	//
	// It is a REFERENCE that must be resolved before a pod can carry it:
	// the control plane resolves it on a hosted env (and re-resolves when
	// the target's URL moves), and pkg/deploy.Render refuses a spec that
	// still holds one rather than render an empty variable.
	// +optional
	WorkloadURL *WorkloadURLRef `json:"workloadURL,omitempty"`

	// ConfigMapRef projects one key of a ConfigMap in the workload's
	// namespace. Full profile only.
	// +optional
	ConfigMapRef *ConfigMapKeyRef `json:"configMapRef,omitempty"`

	// FieldRef projects a pod field through the Downward API
	// (valueFrom.fieldRef.fieldPath). Full profile only.
	// +optional
	FieldRef *FieldRef `json:"fieldRef,omitempty"`
}

type FieldRef struct {
	// FieldPath is the pod field, e.g. metadata.name or status.podIP.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	FieldPath string `json:"fieldPath"`
}

type Invalidate string

type KeyToPath struct {
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Key string `json:"key"`
	// Path is RELATIVE to the mount and may not contain "..", so a key
	// can never be written outside the volume.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=4096
	Path string `json:"path"`
}

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

	Spec   ManagedDatabaseSpec   `json:"spec,omitempty"`
	Status ManagedDatabaseStatus `json:"status,omitempty"`
}

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

type ManagedDatabaseSpec struct {
	// Engine is the database engine. Default postgres.
	// +optional
	// +kubebuilder:default=postgres
	Engine Engine `json:"engine,omitempty"`

	// Instances is how many Postgres instances run: one primary plus
	// (Instances-1) hot standbys. Default 1, ceiling MaxDatabaseInstances.
	// A standby buys failover, not durability.
	// +optional
	// +kubebuilder:default=1
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=3
	Instances int32 `json:"instances,omitempty"`

	// StorageGiB sizes EACH instance's volume, so the cluster provisions
	// Instances × StorageGiB. Default DefaultDatabaseStorageGiB.
	// +optional
	// +kubebuilder:default=10
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=500
	StorageGiB int32 `json:"storageGiB,omitempty"`

	// DeletionPolicy is what deleting this resource does to the data.
	// Default retain.
	// +optional
	// +kubebuilder:default=retain
	DeletionPolicy DeletionPolicy `json:"deletionPolicy,omitempty"`

	// Restore, when set, bootstraps this database from a backup instead of
	// from an empty initdb. DECLARING it is the whole restore procedure:
	// there is no imperative RPC, because a restore that only exists as a
	// command is one nobody can review, repeat, or run at 3am from a git
	// revert.
	//
	// It is honoured ONCE, at bootstrap. A Cluster that already holds data
	// is never re-bootstrapped, so adding this to a live database does
	// nothing — restoring over a running database means declaring a NEW
	// one that names the old as its source, which is also what keeps a
	// mistaken restore from destroying the original.
	// +optional
	Restore *DatabaseRestore `json:"restore,omitempty"`

	// Dashboards opts the database into live dashboard panels: it lets the
	// dashboard role (forge_dash) log in. The role reads only what the
	// project's migrations GRANT it. Nil means disabled, and a disabled
	// database renders the role NOLOGIN with no password, so declaring
	// nothing never leaves a login behind.
	// +optional
	Dashboards *DatabaseDashboards `json:"dashboards,omitempty"`
}

type ManagedDatabaseStatus struct {
	// +optional
	Phase Phase `json:"phase,omitempty"`
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// ClusterName, DatabaseName and RoleName are the identifiers actually
	// created. They are RECORDED rather than re-derived, so that a later
	// change to the naming rule cannot re-point a name that already holds
	// data.
	// +optional
	ClusterName string `json:"clusterName,omitempty"`
	// +optional
	DatabaseName string `json:"databaseName,omitempty"`
	// +optional
	RoleName string `json:"roleName,omitempty"`

	// SecretName is the credential Secret CNPG published, in the Cluster's
	// namespace.
	// +optional
	SecretName string `json:"secretName,omitempty"`

	// EngineVersion is the Postgres version CNPG reports running. It is
	// read back rather than declared, because the version is a platform
	// decision.
	// +optional
	EngineVersion string `json:"engineVersion,omitempty"`

	// ReadyAt is nil until the Cluster has been healthy, with a published
	// credential, at least once.
	// +optional
	ReadyAt *metav1.Time `json:"readyAt,omitempty"`

	// +optional
	Message string `json:"message,omitempty"`

	// Backup is what the executor observed about this database's backups,
	// nil when the environment configures no object store.
	//
	// NIL AND "UNHEALTHY" ARE DIFFERENT ANSWERS, which is why this is a
	// pointer rather than a value. A database nobody is backing up by
	// design must not report the same state as one whose archiving has
	// broken.
	// +optional
	Backup *DatabaseBackupStatus `json:"backup,omitempty"`

	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type ManagedSecretRef struct {
	// Name is the secret's logical name. A BARE LOGICAL NAME: env-var shaped,
	// with no separator to traverse, carrying no customer or environment
	// component, so no spelling of it reaches another customer's value.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern=`^[A-Za-z_][A-Za-z0-9_]*$`
	Name string `json:"name"`

	// Optional tolerates the store having no value: the materializer skips
	// the name, and the pod starts without the variable. Default false: a
	// missing value fails the materialization and nothing starts.
	// +optional
	Optional bool `json:"optional,omitempty"`
}

type PVCVolumeSource struct {
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	ClaimName string `json:"claimName"`
}

type Phase string

type PodSecurity struct {
	// RunAsUser is the uid every container runs as. Must not be 0:
	// runAsNonRoot is always true.
	// +optional
	// +kubebuilder:validation:Minimum=1
	RunAsUser *int64 `json:"runAsUser,omitempty"`
	// RunAsGroup is the primary gid. Must not be 0.
	// +optional
	// +kubebuilder:validation:Minimum=1
	RunAsGroup *int64 `json:"runAsGroup,omitempty"`
	// FSGroup owns mounted volumes. Must not be 0.
	// +optional
	// +kubebuilder:validation:Minimum=1
	FSGroup *int64 `json:"fsGroup,omitempty"`
	// ReadOnlyRootFilesystem false gives the containers a writable root
	// filesystem. Default true.
	// +optional
	ReadOnlyRootFilesystem *bool `json:"readOnlyRootFilesystem,omitempty"`
}

type PolicyRule struct {
	// APIGroups are the API groups; "" is the core group.
	// +kubebuilder:validation:MinItems=1
	APIGroups []string `json:"apiGroups"`

	// Resources are the resource names (plural, lowercase), optionally with
	// a subresource ("pods/log").
	// +kubebuilder:validation:MinItems=1
	Resources []string `json:"resources"`

	// Verbs are the allowed verbs, or "*".
	// +kubebuilder:validation:MinItems=1
	Verbs []string `json:"verbs"`

	// ResourceNames narrows the rule to named objects.
	// +optional
	ResourceNames []string `json:"resourceNames,omitempty"`
}

type Port struct {
	// Name is the port's name, referenced by Services and probes. An
	// IANA_SVC_NAME, as Kubernetes requires of a container port name: at
	// most 15 characters, lowercase alphanumerics and '-'.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=15
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
	Name string `json:"name"`

	// Port is the container port number.
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	Port int32 `json:"port"`

	// Protocol is the transport. Default tcp.
	// +optional
	// +kubebuilder:default=tcp
	Protocol PortProtocol `json:"protocol,omitempty"`

	// AppProtocol is the application protocol the port speaks (h2c, grpc,
	// http, https, ws), set as the Service port's appProtocol so a gateway
	// or mesh can route it correctly. It changes no pod behaviour.
	// +optional
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=`^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?[a-z0-9]([-a-z0-9.]*[a-z0-9])?$`
	AppProtocol string `json:"appProtocol,omitempty"`

	// Expose asks the environment to route a PUBLIC hostname to this port:
	// the gateway when self-hosted, the platform's allocated hostname on
	// hosted. Only a service can expose a port, because only a service
	// has a Service object to route to. At most one port per workload is
	// exposed, because status reports one hostname.
	// +optional
	Expose bool `json:"expose,omitempty"`

	// Domains are CUSTOM hostnames served IN ADDITION to the default
	// hostname. They are only meaningful on the exposed port. The default
	// hostname needs no declaration: hosted allocates a collision-safe one
	// and self-hosted derives one from the env's gateway, so a public
	// workload never has to invent a domain. Hosted verifies ownership of a
	// custom domain before serving it, because on shared infrastructure an
	// unverified hostname is a takeover vector. Self-hosted trusts it.
	// +optional
	// +kubebuilder:validation:MaxItems=8
	Domains []string `json:"domains,omitempty"`
}

type PortProtocol string

type ProbeTimings struct {
	InitialDelaySeconds int32
	PeriodSeconds       int32
	TimeoutSeconds      int32
	FailureThreshold    int32
}

type Probes struct {
	// Port is the container port probed. Unset means the port named http,
	// or the first declared port (see WorkloadSpec.ProbePort).
	// +optional
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	Port int32 `json:"port,omitempty"`

	// ReadinessPath is the HTTP readiness path. Unset means /readyz.
	// +optional
	// +kubebuilder:validation:MaxLength=2048
	// +kubebuilder:validation:Pattern=`^/.*$`
	ReadinessPath string `json:"readinessPath,omitempty"`

	// LivenessPath is the HTTP liveness path. Unset means /healthz.
	// +optional
	// +kubebuilder:validation:MaxLength=2048
	// +kubebuilder:validation:Pattern=`^/.*$`
	LivenessPath string `json:"livenessPath,omitempty"`

	// StartupPath is the HTTP startup-probe path. Unset means no startup
	// probe. The kubelet holds off readiness and liveness until it passes,
	// and a NATIVE sidecar (Container.Native) is only considered started,
	// so the main container only launches, once it does. Unlike the other
	// two paths it has no default: only the container knows what "started"
	// means.
	// +optional
	// +kubebuilder:validation:MaxLength=2048
	// +kubebuilder:validation:Pattern=`^/.*$`
	StartupPath string `json:"startupPath,omitempty"`

	// TCP probes with a TCP connect instead of an HTTP GET. A TCP probe
	// sets no paths.
	// +optional
	TCP bool `json:"tcp,omitempty"`

	// InitialDelaySeconds is the READINESS initial delay. Default 0:
	// readiness is cheap and never restarts, so there is nothing to wait
	// for.
	// +optional
	// +kubebuilder:default=0
	// +kubebuilder:validation:Minimum=0
	InitialDelaySeconds int32 `json:"initialDelaySeconds,omitempty"`

	// PeriodSeconds is the READINESS period. Default 5.
	// +optional
	// +kubebuilder:default=5
	// +kubebuilder:validation:Minimum=1
	PeriodSeconds int32 `json:"periodSeconds,omitempty"`

	// TimeoutSeconds is the per-attempt timeout, for both probes. Default 3,
	// NOT 2. serverkit's readiness handler has a 2s deadline of its own, so a
	// 2s probe timeout would race it and report the handler's slow-but-correct
	// "not ready" as a probe timeout.
	// +optional
	// +kubebuilder:default=3
	// +kubebuilder:validation:Minimum=1
	TimeoutSeconds int32 `json:"timeoutSeconds,omitempty"`

	// FailureThreshold is how many consecutive READINESS failures take a
	// replica out of the endpoints. Default 3.
	// +optional
	// +kubebuilder:default=3
	// +kubebuilder:validation:Minimum=1
	FailureThreshold int32 `json:"failureThreshold,omitempty"`
}

type Profile int

type Resources struct {
	// +optional
	// +kubebuilder:default=250
	// +kubebuilder:validation:Minimum=1
	CPURequestMillicores int64 `json:"cpuRequestMillicores,omitempty"`
	// Unset means equal to the CPU request.
	// +optional
	// +kubebuilder:validation:Minimum=1
	CPULimitMillicores int64 `json:"cpuLimitMillicores,omitempty"`
	// +optional
	// +kubebuilder:default=1073741824
	// +kubebuilder:validation:Minimum=1
	MemoryRequestBytes int64 `json:"memoryRequestBytes,omitempty"`
	// Unset means equal to the memory request.
	// +optional
	// +kubebuilder:validation:Minimum=1
	MemoryLimitBytes int64 `json:"memoryLimitBytes,omitempty"`
}

type RuntimeConfigValue struct {
	// Value is an inline literal.
	// +optional
	// +kubebuilder:validation:MaxLength=32768
	Value *string `json:"value,omitempty"`

	// WorkloadURL resolves to another workload's public URL.
	// +optional
	WorkloadURL *WorkloadURLRef `json:"workloadURL,omitempty"`
}

type SecretKeyRef struct {
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name"`
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Key string `json:"key"`
	// Optional lets the pod start when the Secret or the key does not exist;
	// the variable is then simply unset. It is what the config projection
	// emits for an OPTIONAL sensitive field, whose absence the app already
	// handles. A required reference to a missing key holds the pod in
	// CreateContainerConfigError, with no application log, which is the
	// right outcome only when the value really is required.
	// +optional
	Optional bool `json:"optional,omitempty"`
}

type SecretVolumeSource struct {
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name"`
	// Items selects keys and their file paths. Unset projects every key as
	// a file named after it.
	// +optional
	// +kubebuilder:validation:MaxItems=64
	Items []KeyToPath `json:"items,omitempty"`
	// Optional lets the pod start while the Secret does not exist yet; the
	// kubelet fills the volume in once it appears. A Secret the control plane
	// delivers after the first deploy (forge.ControlPlaneSecret) is mounted
	// this way, so a first deploy never waits on it.
	// +optional
	Optional bool `json:"optional,omitempty"`
}

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

	Spec   StaticSiteSpec   `json:"spec"`
	Status StaticSiteStatus `json:"status,omitempty"`
}

type StaticSiteCDN struct {
	// +kubebuilder:validation:MinLength=1
	URLMap string `json:"urlMap"`

	// Invalidate is the per-deploy cache policy. Empty means entrypoints.
	// The zero value MUST NOT mean all: an unset field is exactly the case
	// where the quota-expensive choice is least likely to have been
	// considered.
	// +optional
	// +kubebuilder:default=entrypoints
	Invalidate Invalidate `json:"invalidate,omitempty"`

	// ExtraInvalidatePaths adds absolute site paths to the entrypoints set,
	// for documents the planner cannot infer (a bare /manifest.json, a
	// service worker). Ignored under none and all.
	// +optional
	ExtraInvalidatePaths []string `json:"extraInvalidatePaths,omitempty"`
}

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

type StaticSiteSpec struct {
	// Bucket is the bucket the site's prefixes live in: gs://name or a bare
	// name. Self-hosted, the user's own bucket. Hosted, the platform assigns
	// a shared bucket and a per-customer prefix and ignores this value.
	// +optional
	// +kubebuilder:validation:MaxLength=222
	Bucket string `json:"bucket,omitempty"`

	// BasePath mounts the site under a sub-path ("/admin"). Empty is the
	// root.
	// +optional
	// +kubebuilder:validation:Pattern=`^/.*$`
	BasePath string `json:"basePath,omitempty"`

	// AssetDir is the build's CONTENT-HASHED asset directory, relative to
	// the site's mount (BasePath): "assets" for a Vite build, "_next/static"
	// for a Next.js export. Every file under it is named for its bytes.
	//
	// It is a SERVING fact, not a build input, because two serving
	// guarantees hang off it and neither can be inferred from a bucket:
	//
	//   - CACHE POLICY. Files under it may be cached forever
	//     (`public, max-age=31536000, immutable`); everything else — the
	//     entry document, config.js, version.json — must revalidate
	//     (`no-cache`), so a deploy is visible on the next load.
	//   - STALE TABS KEEP WORKING. A page loaded before a deploy lazy-loads
	//     chunks the new release no longer contains. The server keeps the
	//     previous releases' files under this directory serveable, so that
	//     import succeeds instead of failing on a 404 (or, worse, on an HTML
	//     fallback parsed as JavaScript).
	//
	// Empty means the build declares none: no immutable caching and no
	// carried-forward assets.
	// +optional
	// +kubebuilder:validation:MaxLength=255
	AssetDir string `json:"assetDir,omitempty"`

	// ReleaseRepository is the OCI repository LiveDigest was pushed to —
	// the whole reference, registry host included, with no tag or digest
	// on it. Together with LiveDigest it is the complete address of the
	// release: `<releaseRepository>@<liveDigest>`.
	//
	// IT IS RECORDED, NOT RECONSTRUCTED, and that is the whole point of
	// the field. A site's release goes to the frontend's OWN declared
	// image reference plus the platform's layout segment
	// (deploytarget.HostedStaticRepository), which is a reference only the
	// builder knows: it may be an org's registry subtree, or a registry
	// the platform does not host at all. Anything that recomposed a path
	// from a registry base, an org id and a site name would be writing
	// down a second, independent derivation of where the bytes are — and
	// when the two disagree, the puller 404s on an artifact that exists.
	// That is exactly the defect this field closes, and it is the same
	// rule a workload's image already follows: the reference carries its
	// registry, and the release ledger keys artifacts by full reference.
	//
	// WHERE a caller may push is therefore a platform policy enforced as
	// ADMISSION on this recorded value — a reference inside the platform's
	// own registry must be inside that org's subtree — never by deriving
	// the value and calling the derivation a boundary.
	//
	// Empty before the first deploy, like LiveDigest. A spec carrying a
	// digest but no repository is not pullable, and whoever executes it
	// must refuse rather than guess a path.
	// +optional
	// +kubebuilder:validation:MaxLength=512
	ReleaseRepository string `json:"releaseRepository,omitempty"`

	// LiveDigest is the release the live prefix must serve. A digest, never
	// a tag: a tag is a mutable pointer, and re-pointing one would void
	// "the bytes that passed staging are the bytes in prod". Empty before
	// the first deploy. Addressed within ReleaseRepository.
	// +optional
	// +kubebuilder:validation:Pattern=`^sha256:[a-f0-9]{64}$`
	LiveDigest string `json:"liveDigest,omitempty"`

	// PreviousDigest is the release that was live before LiveDigest.
	// Retention never deletes it: pages loaded from it moments ago are still
	// fetching its hashed assets.
	// +optional
	// +kubebuilder:validation:Pattern=`^sha256:[a-f0-9]{64}$`
	PreviousDigest string `json:"previousDigest,omitempty"`

	// RetainedDigests are releases that MUST survive retention (every digest
	// an environment is promoted to, plus any pin), projected from the
	// release ledger. A retention planner that cannot resolve its protected
	// set deletes NOTHING. It never reads "I know of nothing to protect" as
	// "nothing needs protecting".
	// +optional
	RetainedDigests []string `json:"retainedDigests,omitempty"`

	// KeepReleases is how many archived releases to retain, newest first.
	// Unset means DefaultKeepReleases. An explicit 0 retains everything.
	// Otherwise it must be at least MinKeepReleases, because keeping fewer
	// than the live release plus its predecessor would delete assets pages
	// loaded moments ago still fetch.
	//
	// A POINTER because there are three states. control-plane's plain
	// omitempty int32 made "unset" and "retain everything" the same value,
	// so a CR that omitted the field silently disabled retention. forge's
	// KCL defaulted to 10. Both are honoured now: nil is the default, and
	// 0 is a deliberate choice.
	// +optional
	// +kubebuilder:validation:Minimum=0
	KeepReleases *int32 `json:"keepReleases,omitempty"`

	// Entrypoints are the site-absolute paths that cannot be
	// content-addressed and are invalidated on every deploy. Empty uses the
	// planner's default set.
	// +optional
	Entrypoints []string `json:"entrypoints,omitempty"`

	// CDN is the CDN in front of the bucket. Omitted means a bucket served
	// directly, with no invalidation.
	// +optional
	CDN *StaticSiteCDN `json:"cdn,omitempty"`

	// Domains are custom hostnames, in addition to the default one.
	// +optional
	// +kubebuilder:validation:MaxItems=8
	Domains []string `json:"domains,omitempty"`

	// RuntimeConfig is the site's runtime configuration document: the
	// object the browser receives as window.__FORGE_CONFIG__, keyed by the
	// name the bundle reads (API_URL, OIDC_ISSUER, ...).
	//
	// It is SPEC, not a file inside the release, and that is the point.
	// A release artifact that carried its own config.js would be frozen to
	// the environment it was built for, and promoting it would ship
	// staging's backend URL to production. Keeping the document here makes
	// the artifact environment-agnostic: whoever executes the spec writes
	// `live/<basePath>/config.js` AFTER syncing live/ from the release, on
	// every sync (a sync prunes files the release does not contain), as
	//
	//	window.__FORGE_CONFIG__ = {"KEY": "resolved value", ...};
	//
	// (pkg/deploy.RuntimeConfigJS renders exactly that document.) An entry
	// is either a literal or a reference to another workload's URL, which
	// is resolved where the URL is known: by the control plane for a
	// hosted env, at render time by forge otherwise. See RuntimeConfigValue.
	// +optional
	// +kubebuilder:validation:MaxProperties=128
	RuntimeConfig map[string]RuntimeConfigValue `json:"runtimeConfig,omitempty"`
}

type StaticSiteStatus struct {
	TierStatus `json:",inline"`

	// BucketPrefix is the site's root prefix within its bucket, RECORDED
	// rather than re-derived, so that a later change to the derivation rule
	// cannot silently re-point a prefix that already holds live objects.
	// +optional
	BucketPrefix string `json:"bucketPrefix,omitempty"`

	// LiveDigest is what the live prefix was CONFIRMED to serve. It lags
	// spec.liveDigest until a sync succeeds, and that gap is the drift
	// signal. PreviousDigest is its confirmed predecessor.
	// +optional
	LiveDigest string `json:"liveDigest,omitempty"`
	// +optional
	PreviousDigest string `json:"previousDigest,omitempty"`

	// RecentDigests are the releases the live prefix CONFIRMED serving
	// before LiveDigest, newest first (PreviousDigest leads). The executor
	// keeps their files under spec.assetDir serveable — a page loaded from
	// one of them still lazy-loads its chunks after a deploy — so retention
	// must never delete them. Ordered history that a bucket listing cannot
	// give: archive prefixes carry no time.
	// +optional
	// +kubebuilder:validation:MaxItems=32
	RecentDigests []string `json:"recentDigests,omitempty"`

	// ReleaseCount is how many archived releases the last retention pass
	// observed.
	// +optional
	// +kubebuilder:validation:Minimum=0
	ReleaseCount int32 `json:"releaseCount,omitempty"`

	// LastSyncedAt is nil until the live prefix has synced once.
	// +optional
	LastSyncedAt *metav1.Time `json:"lastSyncedAt,omitempty"`
}

type TaintEffect string

type TierStatus struct {
	// +optional
	Phase Phase `json:"phase,omitempty"`

	// ObservedGeneration is the metadata.generation this status describes. A
	// status whose ObservedGeneration lags the object's generation describes
	// a PREVIOUS spec, and a reader must not treat it as current.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Hostname is the hostname serving this workload, and URL is its https://
	// form. On hosted this is the ALLOCATED platform hostname, recorded only
	// after the allocator committed it. Custom domains from spec.domains are
	// served in addition to it.
	// +optional
	Hostname string `json:"hostname,omitempty"`
	// +optional
	URL string `json:"url,omitempty"`

	// Message is the human-readable reason for the current phase.
	// +optional
	Message string `json:"message,omitempty"`

	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type Toleration struct {
	// Key is the taint key. Empty, with operator Exists, tolerates every
	// taint.
	// +optional
	// +kubebuilder:validation:MaxLength=316
	Key string `json:"key,omitempty"`

	// Operator is Exists or Equal. Unset means Equal (Kubernetes' default).
	// +optional
	Operator TolerationOperator `json:"operator,omitempty"`

	// Value is the taint value to match, for operator Equal.
	// +optional
	// +kubebuilder:validation:MaxLength=63
	Value string `json:"value,omitempty"`

	// Effect is the taint effect to match. Unset matches every effect.
	// +optional
	Effect TaintEffect `json:"effect,omitempty"`

	// TolerationSeconds bounds how long a NoExecute taint is tolerated
	// before eviction. Unset means forever.
	// +optional
	// +kubebuilder:validation:Minimum=0
	TolerationSeconds *int64 `json:"tolerationSeconds,omitempty"`
}

type TolerationOperator string

type Volume struct {
	// Name is the volume name, unique within the pod.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
	Name string `json:"name"`

	// MountPath is the absolute path the volume mounts at in the main
	// container.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=4096
	// +kubebuilder:validation:Pattern=`^/.*$`
	MountPath string `json:"mountPath"`

	// ReadOnly mounts the volume read-only. Secret and ConfigMap volumes
	// are conventionally read-only; an emptyDir is usually writable scratch.
	// +optional
	ReadOnly bool `json:"readOnly,omitempty"`

	// Source is where the volume's content comes from: exactly one kind.
	Source VolumeSource `json:"source"`
}

type VolumeSource struct {
	// Secret projects a Secret in the workload's namespace as files.
	// +optional
	Secret *SecretVolumeSource `json:"secret,omitempty"`

	// ConfigMap projects a ConfigMap in the workload's namespace as files.
	// +optional
	ConfigMap *ConfigMapVolumeSource `json:"configMap,omitempty"`

	// EmptyDir is pod-lifetime scratch space, which is the way to give a
	// workload a writable path under forge's read-only root filesystem.
	// +optional
	EmptyDir *EmptyDirVolumeSource `json:"emptyDir,omitempty"`

	// PVC mounts an EXISTING PersistentVolumeClaim. For storage forge
	// provisions, use WorkloadSpec.StorageGiB.
	// +optional
	PVC *PVCVolumeSource `json:"pvc,omitempty"`
}

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

	Spec   WorkloadSpec   `json:"spec"`
	Status WorkloadStatus `json:"status,omitempty"`
}

type WorkloadKind string

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

type WorkloadSpec struct {
	// Kind is how the workload runs. Default service.
	// +optional
	// +kubebuilder:default=service
	Kind WorkloadKind `json:"kind,omitempty"`

	// Image is the container image, resolved by the lowering (the build
	// output, or an author-named third-party image). ProfileRestricted
	// also requires it to be registry-qualified and pinned, because the
	// platform pulls it from a registry the hosted user does not control. A
	// cluster the author operates may run a locally imported bare name.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=500
	Image string `json:"image"`

	// Command overrides the image's entrypoint. Rare: a forge-built
	// project binary is selected by Args, not by replacing the entrypoint.
	// +optional
	// +kubebuilder:validation:MaxItems=64
	// +kubebuilder:validation:items:MaxLength=4096
	Command []string `json:"command,omitempty"`

	// Args are the entrypoint's arguments, typically the project binary's
	// subcommand. The host runtime derives its command from the build plus
	// these same args, so they are stated once for every runtime.
	// +optional
	// +kubebuilder:validation:MaxItems=64
	// +kubebuilder:validation:items:MaxLength=4096
	Args []string `json:"args,omitempty"`

	// Replicas is the pod count for a service, worker or operator. Default
	// 1. A batch kind's concurrency belongs to its Job or CronJob, and a
	// tool is never scheduled, so neither may set more than one.
	// +optional
	// +kubebuilder:default=1
	// +kubebuilder:validation:Minimum=1
	Replicas int32 `json:"replicas,omitempty"`

	// Resources is the compute request and limit. Omitted means the entry
	// shape (250m / 1 GiB).
	// +optional
	Resources Resources `json:"resources,omitempty"`

	// Env is the container environment. There is no portable entry-count limit:
	// exec limits apply to the resolved environment and arguments in bytes,
	// including values supplied by secret references at runtime.
	// +optional
	// +listType=map
	// +listMapKey=name
	Env []EnvVar `json:"env,omitempty"`

	// Ports are the ports the container listens on. A service's ports are
	// all on its ClusterIP Service. An operator's and a worker's are
	// container ports only, because nothing resolves them by name.
	// +optional
	// +listType=map
	// +listMapKey=name
	// +kubebuilder:validation:MaxItems=16
	Ports []Port `json:"ports,omitempty"`

	// Probes are the readiness and liveness probes. Omitted means the
	// policy in EffectiveProbes: TCP on the first port for a service that
	// declares ports, and none for anything else. The lowering writes HTTP
	// /readyz + /healthz explicitly for a service forge built, and for a
	// forge-built operator that declares ports.
	// +optional
	Probes *Probes `json:"probes,omitempty"`

	// StorageGiB provisions a ReadWriteOnce PersistentVolumeClaim of this
	// many GiB, mounted at /data. Zero means stateless.
	//
	// A ReadWriteOnce volume can be mounted by one pod at a time, so a
	// workload with storage runs exactly one replica with a Recreate
	// rollout. A rolling update would start the new pod while the old one
	// still holds the volume, and wedge. A bound PVC keeps existing, and on
	// hosted keeps billing, while the workload is scaled to zero. That is
	// deliberate: it is what the cloud itself charges.
	// +optional
	// +kubebuilder:validation:Minimum=0
	StorageGiB int32 `json:"storageGiB,omitempty"`

	// Schedule is a cron's schedule: a 5-field cron expression or one of
	// @hourly, @daily, @weekly, @monthly, @yearly.
	// +optional
	// +kubebuilder:validation:MaxLength=128
	Schedule string `json:"schedule,omitempty"`

	// Before names the workloads that must not start until this job exits
	// 0, or [BeforeAll] for every workload in the environment.
	// +optional
	// +kubebuilder:validation:MaxItems=64
	Before []string `json:"before,omitempty"`

	// DeployPhase places a standalone job in the deploy. Unset means
	// pre-rollout (EffectiveDeployPhase). There is no default marker: a
	// static default would be stamped on every kind, and Validate would
	// then refuse the CR it was handed.
	// +optional
	DeployPhase DeployPhase `json:"deployPhase,omitempty"`

	// NamespacedRBAC grants a Role + RoleBinding in the workload's own
	// namespace, in addition to forge's default config-read rules. The Role
	// is rendered whenever the workload has ANY RBAC (either tier, or kind
	// operator); with none, there is no Role at all and no mounted token.
	// +optional
	// +kubebuilder:validation:MaxItems=64
	NamespacedRBAC []PolicyRule `json:"namespacedRBAC,omitempty"`

	// ClusterRBAC grants a ClusterRole + ClusterRoleBinding. Any scheduled
	// kind may declare it (Full profile only): an operator watches its CRDs
	// cluster-wide, and a service may legitimately resolve resources across
	// namespaces (a proxy routing to per-workspace objects) without being a
	// controller. It ADDS to the namespaced Role rather than replacing it:
	// the ClusterRole carries only cluster-scoped intent (these rules, and an
	// operator's CRD-derived rules), while the config-read defaults and an
	// operator's leader-election lease stay in the namespaced Role. Both
	// bind the one ServiceAccount, so NamespacedRBAC and ClusterRBAC may be
	// declared together, each at its own scope.
	// +optional
	// +kubebuilder:validation:MaxItems=64
	ClusterRBAC []PolicyRule `json:"clusterRBAC,omitempty"`

	// CRDs are the custom resource kinds an operator's manager owns. May be
	// empty: an operator that owns none yet, or reconciles built-in kinds.
	// +optional
	// +kubebuilder:validation:MaxItems=64
	// +kubebuilder:validation:items:Pattern=`^[A-Z][A-Za-z0-9]*$`
	CRDs []string `json:"crds,omitempty"`

	// Group is the API group of an operator's CRDs.
	// +optional
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
	Group string `json:"group,omitempty"`

	// Version is the API version of an operator's CRDs.
	// +optional
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=`^v[0-9]+((alpha|beta)[0-9]+)?$`
	Version string `json:"version,omitempty"`

	// LeaderElection turns an operator's leader election on or off. Unset
	// means on (EffectiveLeaderElection). A pointer, with no default
	// marker, because the default is true only for an operator. A static
	// default would stamp it onto every kind.
	// +optional
	LeaderElection *bool `json:"leaderElection,omitempty"`

	// ServiceAccountAnnotations are stamped on the workload's generated
	// ServiceAccount and on no other object. Cloud workload identity is the
	// case it exists for: GKE reads iam.gke.io/gcp-service-account, and EKS
	// reads eks.amazonaws.com/role-arn, off the KSA the pod runs as.
	// +optional
	// +kubebuilder:validation:MaxProperties=32
	ServiceAccountAnnotations map[string]string `json:"serviceAccountAnnotations,omitempty"`

	// Sidecars are additional containers in the workload's pod: a Cloud SQL
	// Auth Proxy, a registry forwarder. They get the same hardened
	// securityContext as the main container.
	// +optional
	// +listType=map
	// +listMapKey=name
	// +kubebuilder:validation:MaxItems=8
	Sidecars []Container `json:"sidecars,omitempty"`

	// Volumes are extra pod volumes, each mounted into the main container.
	// For storage forge provisions, use StorageGiB.
	// +optional
	// +listType=map
	// +listMapKey=name
	// +kubebuilder:validation:MaxItems=32
	Volumes []Volume `json:"volumes,omitempty"`

	// ServiceAccount names an EXISTING ServiceAccount to run as, instead of
	// the one forge generates. The case is cloud workload identity bound to
	// a ServiceAccount that other infrastructure owns. forge then renders no
	// ServiceAccount, Role or binding for the workload, so this is mutually
	// exclusive with NamespacedRBAC, ClusterRBAC and
	// ServiceAccountAnnotations: each of those describes the generated
	// ServiceAccount, which no longer exists.
	//
	// The renderer leaves the pod's automountServiceAccountToken UNSET when
	// this is set, so the named ServiceAccount's own
	// automountServiceAccountToken decides and its owner controls it. forge
	// cannot know whether that identity calls the Kubernetes API, and a
	// pod-level false would silently disable one that does. (A generated
	// ServiceAccount's token mounts only when the workload has RBAC.)
	// +optional
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
	ServiceAccount string `json:"serviceAccount,omitempty"`

	// NodeSelector constrains the pods to nodes with these labels.
	// +optional
	// +kubebuilder:validation:MaxProperties=32
	NodeSelector map[string]string `json:"nodeSelector,omitempty"`

	// Tolerations let the pods schedule onto tainted nodes.
	// +optional
	// +kubebuilder:validation:MaxItems=32
	Tolerations []Toleration `json:"tolerations,omitempty"`

	// PodAnnotations are stamped on the pod template.
	// +optional
	// +kubebuilder:validation:MaxProperties=64
	PodAnnotations map[string]string `json:"podAnnotations,omitempty"`

	// Strategy is how the Deployment replaces its pods on a rollout.
	//
	// Unset is Kubernetes' default, RollingUpdate, which surges a new pod
	// before the old one stops — so a workload whose replica count is a
	// CORRECTNESS bound rather than a capacity choice (a sweeper that is not
	// idempotent under concurrency) runs twice for the length of a rollout,
	// which `replicas: 1` looks like it prevents and does not. Declare
	// Recreate there and accept the gap with no pod.
	//
	// RollingUpdate alongside storageGiB is REFUSED: a ReadWriteOnce volume
	// is mounted by one pod at a time, so the surge pod can never start and
	// the rollout wedges. Storage alone already renders Recreate.
	// +optional
	Strategy DeploymentStrategy `json:"strategy,omitempty"`

	// PriorityClassName names a PriorityClass that ranks these pods against
	// everything else competing for a node: the scheduler places a higher
	// priority pod first, and a preempting class evicts lower priority pods
	// to make room. The case is a workload sharing nodes with pods that
	// already carry a class — without one it is priority 0 and loses every
	// contest, so a rollout's surge pod can be preempted repeatedly and take
	// minutes to land.
	//
	// The class is CLUSTER-SCOPED and must already exist: Kubernetes REFUSES
	// a pod naming a PriorityClass the cluster does not have, so the class
	// has to be applied to every cluster this workload lands on, before the
	// pods that name it. Unset leaves the pod at the cluster's default
	// (globalDefault, else 0). Full profile only.
	// +optional
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
	PriorityClassName string `json:"priorityClassName,omitempty"`

	// EnableServiceLinks opts the pods IN to Kubernetes' service links: an
	// env var per Service in the namespace (<NAME>_PORT=tcp://ip:port,
	// <NAME>_SERVICE_HOST, <NAME>_SERVICE_PORT, ...). Unset (false) renders
	// pod.enableServiceLinks: false, because those names are not namespaced
	// to anything: a Service called `temporal` injects TEMPORAL_PORT, which
	// a typed config loader then parses as a port number and the process
	// CrashLoops at boot (reliant's daemon-gateway, 2026-10-21; Zitadel's
	// ZITADEL_PORT before it). Resolve a Service through DNS
	// (<svc>.<namespace>.svc) or an explicit env var instead. Set this only
	// for an image that reads the injected variables. Full profile only.
	// +optional
	EnableServiceLinks bool `json:"enableServiceLinks,omitempty"`

	// TerminationGracePeriodSeconds overrides the drain-derived grace
	// period (PRE_STOP_DELAY + SHUTDOWN_TIMEOUT + 5 from the workload's env).
	// For a process whose shutdown budget is not expressed in those env
	// vars: a Temporal worker finishing in-flight activities needs 60s.
	// Full profile only. 0 is honoured (SIGKILL immediately).
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=3600
	TerminationGracePeriodSeconds *int32 `json:"terminationGracePeriodSeconds,omitempty"`

	// ActiveDeadlineSeconds bounds a job or cron run: Kubernetes fails the
	// Job (Job.spec.activeDeadlineSeconds) once it has run this long, and
	// the host runtime kills the process. A one-shot that can hang would
	// otherwise block a deploy or `forge env up` forever. Allowed under
	// every profile: a timeout only ever shortens what runs.
	// +optional
	// +kubebuilder:validation:Minimum=1
	ActiveDeadlineSeconds *int64 `json:"activeDeadlineSeconds,omitempty"`

	// SecurityContext loosens forge's pod identity defaults for an image
	// that needs it: a Next.js standalone image that runs as uid 1000 and
	// writes into its own tree. Full profile only. It is deliberately
	// NOT a Kubernetes securityContext passthrough: no privileged, no
	// capabilities, no host namespaces, and runAsNonRoot stays forced, so
	// every pod is still Pod Security `restricted`.
	// +optional
	SecurityContext *PodSecurity `json:"securityContext,omitempty"`
}

type WorkloadStatus struct {
	TierStatus `json:",inline"`

	// ServiceName is the Service the hostname routes to. Empty for a kind
	// with no Service object.
	// +optional
	ServiceName string `json:"serviceName,omitempty"`

	// WorkloadName is the Deployment, Job or CronJob carrying the pods.
	// +optional
	WorkloadName string `json:"workloadName,omitempty"`

	// ReadyReplicas is the API server's own observed ready count. It is
	// this resource's liveness proof, and it is why a workload that never
	// started bills nothing.
	// +optional
	// +kubebuilder:validation:Minimum=0
	ReadyReplicas int32 `json:"readyReplicas,omitempty"`

	// UpdatedReplicas is how many replicas are running the CURRENT pod
	// template — the one carrying ObservedImage — and are ready.
	//
	// It exists because ReadyReplicas alone cannot tell a finished rollout
	// from a failing one. Under RollingUpdate the old replicas stay ready
	// while the new ones crash-loop, so ReadyReplicas ≥ desired holds
	// throughout, and a reader that gates on it alone passes a release
	// that never served a request. UpdatedReplicas is the count that goes
	// to zero in exactly that case, which is why it is the field a rollout
	// gate reads.
	// +optional
	// +kubebuilder:validation:Minimum=0
	UpdatedReplicas int32 `json:"updatedReplicas,omitempty"`

	// DesiredReplicas is how many the controller is working toward. It is
	// reported rather than inferred from spec.replicas because the two can
	// legitimately differ — mid-scale, or while a status describes a
	// previous generation — and comparing UpdatedReplicas against the
	// spec in that window would read a normal scale as a stalled rollout.
	// +optional
	// +kubebuilder:validation:Minimum=0
	DesiredReplicas int32 `json:"desiredReplicas,omitempty"`

	// ObservedImage is the image the running workload was CONFIRMED to
	// carry. It lags spec.image until a rollout completes, and that gap is
	// the drift signal.
	//
	// CONFIRMED means the rollout to that template finished — the same
	// completion test `kubectl rollout status` applies. Until it does, the
	// field keeps its PREVIOUS value, the image last confirmed running,
	// because reporting the pod template's image the moment it is written
	// would make "observed" mean "declared" and leave nothing to compare
	// a desired digest against.
	// +optional
	ObservedImage string `json:"observedImage,omitempty"`

	// LastReadyAt is nil until the workload has had a ready replica at
	// least once. A nil value is the machine-readable form of "declared,
	// never ran".
	// +optional
	LastReadyAt *metav1.Time `json:"lastReadyAt,omitempty"`
}

type WorkloadURLRef struct {
	// Name is the target workload's name (its metadata.name).
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
	Name string `json:"name"`
}