jobdef

type Arrival struct {
	Event     *ArrivalEvent `yaml:"event,omitempty" json:"event,omitempty"`
	Watermark string        `yaml:"watermark,omitempty" json:"watermark,omitempty"`
}

type ArrivalEvent struct {
	Type   string            `yaml:"type,omitempty" json:"type,omitempty"`
	Filter map[string]string `yaml:"filter,omitempty" json:"filter,omitempty"`
}

type CacheConfig struct {
	Enabled bool
	TTL     time.Duration
	Version int
	// Chain selects how predecessor identity enters this step's cache key:
	// CacheChainTransitive (default, today's behaviour) or CacheChainValues.
	// It layers job -> step exactly like PinDigests, so `metadata.cache.chain`
	// is a job-wide default.
	Chain string
	// TTLNever records the literal `ttl: never`, which suppresses the expiry
	// entirely (nil ExpiresAt) regardless of any inherited TTL default. It is
	// distinct from TTL == 0, which means "inherit / no explicit TTL" and is
	// still subject to the CAESIUM_CACHE_TTL default.
	TTLNever bool
	// PinDigests resolves each step's image tag to its content digest and folds
	// the digest (not the mutable tag) into the cache key, so a moving :latest
	// produces a cache miss rather than a stale hit.
	PinDigests bool
	// DigestTTL bounds how long a resolved tag->digest mapping is reused before
	// re-resolution. It is a perf cache: within the window a moved tag is not
	// re-detected. 0 means "re-resolve every check" (immediate moved-tag
	// detection, at a registry round-trip per check). Defaults to
	// CAESIUM_CACHE_DIGEST_TTL; only meaningful when PinDigests is on.
	DigestTTL time.Duration
}

type Callback struct {
	Type          string         `yaml:"type" json:"type"`
	Configuration map[string]any `yaml:"configuration" json:"configuration"`
}

type ClaimTemplate struct {
	StorageClass string            `yaml:"storageClass,omitempty" json:"storageClass,omitempty"`
	Size         string            `yaml:"size,omitempty" json:"size,omitempty"`
	AccessMode   string            `yaml:"accessMode,omitempty" json:"accessMode,omitempty"`
	Labels       map[string]string `yaml:"labels,omitempty" json:"labels,omitempty"`
	Annotations  map[string]string `yaml:"annotations,omitempty" json:"annotations,omitempty"`
}

type Concurrency struct {
	MaxRuns  int    `yaml:"maxRuns,omitempty" json:"maxRuns,omitempty"`
	Strategy string `yaml:"strategy,omitempty" json:"strategy,omitempty"`
}

type ConsumedDataset struct {
	// Name is the dataset identity this step reads.
	Name string `yaml:"name" json:"name"`
	// Schema is the JSON Schema subset this consumer requires from the dataset.
	// Optional: a consumer without a declared schema participates in name-level
	// contract edges only.
	Schema map[string]any `yaml:"schema,omitempty" json:"schema,omitempty"`
}

type Definition struct {
	Schema     string     `yaml:"$schema,omitempty" json:"$schema,omitempty"`
	APIVersion string     `yaml:"apiVersion" json:"apiVersion"`
	Kind       string     `yaml:"kind" json:"kind"`
	Metadata   Metadata   `yaml:"metadata" json:"metadata"`
	Trigger    Trigger    `yaml:"trigger" json:"trigger"`
	Callbacks  []Callback `yaml:"callbacks,omitempty" json:"callbacks,omitempty"`
	Volumes    []Volume   `yaml:"volumes,omitempty" json:"volumes,omitempty"`
	Steps      []Step     `yaml:"steps" json:"steps"`
}

type FanOut struct {
	From          string `yaml:"from" json:"from"`
	Env           string `yaml:"env,omitempty" json:"env,omitempty"`
	MaxPartitions int    `yaml:"maxPartitions" json:"maxPartitions"`
	MaxParallel   int    `yaml:"maxParallel,omitempty" json:"maxParallel,omitempty"`
	OnEmpty       string `yaml:"onEmpty,omitempty" json:"onEmpty,omitempty"`
	FailurePolicy string `yaml:"failurePolicy,omitempty" json:"failurePolicy,omitempty"`
}

type Kueue struct {
	// QueueName is the Kueue LocalQueue (in the pod's namespace) to admit
	// through. It is the value of the `kueue.x-k8s.io/queue-name` label.
	// omitempty keeps the marshaled form symmetric with
	// container.KubernetesSpec.QueueName; an empty value is unreachable through
	// normal parsing because Validate() rejects a blank queueName.
	QueueName string `yaml:"queueName,omitempty" json:"queueName,omitempty"`
}

type Metadata struct {
	Alias            string            `yaml:"alias" json:"alias"`
	Labels           map[string]string `yaml:"labels,omitempty" json:"labels,omitempty"`
	Annotations      map[string]string `yaml:"annotations,omitempty" json:"annotations,omitempty"`
	MaxParallelTasks int               `yaml:"maxParallelTasks,omitempty" json:"maxParallelTasks,omitempty"`
	TaskTimeout      time.Duration     `yaml:"taskTimeout,omitempty" json:"taskTimeout,omitempty"`
	RunTimeout       time.Duration     `yaml:"runTimeout,omitempty" json:"runTimeout,omitempty"`
	Priority         string            `yaml:"priority,omitempty" json:"priority,omitempty"`
	Concurrency      *Concurrency      `yaml:"concurrency,omitempty" json:"concurrency,omitempty"`
	RateLimits       []RateLimit       `yaml:"rateLimits,omitempty" json:"rateLimits,omitempty"`
	// SLA defines the service-level agreement for this job. It supports two
	// modes that may be used independently or together:
	//   duration    — max run duration before an SLA miss alert (relative to
	//                 run start; does not cancel execution).
	//   completedBy — wall-clock time of day ("HH:MM", UTC) by which the job
	//                 must have a successfully completed run. Alerts even if
	//                 no run has started.
	SLA *SLAConfig `yaml:"sla,omitempty" json:"sla,omitempty"`
	// SchemaValidation controls runtime output schema validation.
	// Values: "" (disabled), "warn" (log violations), "fail" (fail task on violation).
	SchemaValidation string `yaml:"schemaValidation,omitempty" json:"schemaValidation,omitempty"`
	// ReplaySafe marks every step in this job as eligible for quarantined replay.
	// The effective per-step value is snapshotted onto TaskRun when the task runs.
	ReplaySafe                   bool              `yaml:"replaySafe,omitempty" json:"replaySafe,omitempty"`
	Cache                        any               `yaml:"cache,omitempty" json:"cache"`
	ServiceAccountName           string            `yaml:"serviceAccountName,omitempty" json:"serviceAccountName,omitempty"`
	PodAnnotations               map[string]string `yaml:"podAnnotations,omitempty" json:"podAnnotations,omitempty"`
	AutomountServiceAccountToken *bool             `yaml:"automountServiceAccountToken,omitempty" json:"automountServiceAccountToken,omitempty"`
	// Datasets declares the external source datasets this job's steps consume.
	// It is scheduling metadata for freshness and does not affect the cache hash.
	Datasets *MetadataDatasets `yaml:"datasets,omitempty" json:"datasets,omitempty"`
	// Remediation declares this job's opt-in to autonomous incident
	// remediation (agent-in-the-loop-remediation Stream E): which
	// AgentProfile to use, which failure classes are in scope, the tiered
	// action catalog the agent (or a deterministic rule) may exercise
	// autonomously, and the escalation fallback. It is server-enforced
	// scheduling/policy metadata, not a step-execution input, and does not
	// affect the cache hash.
	Remediation *MetadataRemediation `yaml:"remediation,omitempty" json:"remediation,omitempty"`
}

type MetadataDatasets struct {
	Sources []SourceDataset `yaml:"sources,omitempty" json:"sources,omitempty"`
	// SkipWhenFresh controls P1 cron skipping. Nil means the default: true when a
	// job declares datasets. This is scheduling metadata and does not affect cache
	// identity.
	SkipWhenFresh *bool `yaml:"skipWhenFresh,omitempty" json:"skipWhenFresh,omitempty"`
}

type MetadataRemediation struct {
	// Profile references an AgentProfile by name. AgentProfile is
	// server-side state (api/rest/controller/agentprofile), so offline
	// `caesium job lint` cannot verify this reference — it emits a scope
	// note instead. Server-side lint (POST /v1/jobdefs/lint) and the apply
	// transaction both verify it.
	Profile string `yaml:"profile" json:"profile"`
	// Classes lists the failure classes this policy applies to.
	Classes []string `yaml:"classes,omitempty" json:"classes,omitempty"`
	// MaxAttempts bounds how many remediation attempts an incident may take
	// before it force-escalates.
	MaxAttempts int `yaml:"maxAttempts,omitempty" json:"maxAttempts,omitempty"`
	// Autonomy declares which actions may run without a human and under what
	// constraints.
	Autonomy *RemediationAutonomy `yaml:"autonomy,omitempty" json:"autonomy,omitempty"`
	// Escalation configures the forced hand-off when remediation doesn't
	// resolve the incident within Escalation.After.
	Escalation *RemediationEscalation `yaml:"escalation,omitempty" json:"escalation,omitempty"`
}

type ProducedDataset struct {
	// Name is the dataset identity (keyed on name in v1; namespace is reserved).
	Name string `yaml:"name" json:"name"`
	// Schema is an inline JSON Schema describing the dataset this step produces.
	Schema map[string]any `yaml:"schema,omitempty" json:"schema,omitempty"`
	// SchemaFrom names a step-local schema source. The only supported value is
	// "output", which reuses this step's outputSchema.
	SchemaFrom string `yaml:"schemaFrom,omitempty" json:"schemaFrom,omitempty"`
	// Version is bumped by authors when an intentional dataset contract break is
	// introduced.
	Version int `yaml:"version,omitempty" json:"version,omitempty"`
	// Freshness is the target staleness SLO as a Go duration string (e.g. "6h").
	Freshness string `yaml:"freshness,omitempty" json:"freshness,omitempty"`
	// MaxStaleness is the hard bound whose breach emits freshness_violated.
	MaxStaleness string `yaml:"maxStaleness,omitempty" json:"maxStaleness,omitempty"`
	// Watermark names the output key this step emits to advance the dataset.
	Watermark *Watermark `yaml:"watermark,omitempty" json:"watermark,omitempty"`
}

type RateLimit struct {
	Resource string `yaml:"resource" json:"resource"`
	Limit    int    `yaml:"limit" json:"limit"`
	Window   string `yaml:"window" json:"window"`
}

type RemediationAutonomy struct {
	// Allow lists the actions this job permits to run autonomously (subject
	// to each action's own tier semantics — tier 3 always creates an
	// ApprovalRequest no matter what allow contains).
	Allow []string `yaml:"allow,omitempty" json:"allow,omitempty"`
	// ParamOverrides whitelists the rerun_with_params values allowed per
	// trigger.defaultParams key. Every key must name an existing
	// trigger.defaultParams entry.
	ParamOverrides map[string][]string `yaml:"paramOverrides,omitempty" json:"paramOverrides,omitempty"`
	// PerClass optionally narrows the allow list for a specific failure class.
	PerClass map[string]RemediationClassPolicy `yaml:"perClass,omitempty" json:"perClass,omitempty"`
	// RequireApproval lists actions that must create an ApprovalRequest for
	// this job even if the action's own default tier would otherwise permit
	// autonomous execution.
	RequireApproval []string `yaml:"requireApproval,omitempty" json:"requireApproval,omitempty"`
}

type RemediationClassPolicy struct {
	Allow []string `yaml:"allow,omitempty" json:"allow,omitempty"`
}

type RemediationEscalation struct {
	// Channel names a NotificationChannel (server-side state; unverified by
	// offline lint, same posture as Profile).
	Channel string `yaml:"channel,omitempty" json:"channel,omitempty"`
	// After is the wall-clock cap, as a Go duration string, before the
	// incident is force-escalated to Channel.
	After string `yaml:"after,omitempty" json:"after,omitempty"`
}

type SLAConfig struct {
	// Duration is the maximum time a run may take before an SLA miss alert is
	// emitted, measured from the run's start time. Does not cancel execution.
	Duration time.Duration `yaml:"duration,omitempty" json:"duration,omitempty"`

	// CompletedBy is a wall-clock time of day in "HH:MM" format (UTC) by
	// which the job must have a successfully completed run. If no run has
	// completed by this time, an SLA miss alert is emitted — even if the job
	// was never triggered.
	CompletedBy string `yaml:"completedBy,omitempty" json:"completedBy,omitempty"`
}

type SourceDataset struct {
	Name          string   `yaml:"name" json:"name"`
	ExpectedEvery string   `yaml:"expectedEvery,omitempty" json:"expectedEvery,omitempty"`
	Arrival       *Arrival `yaml:"arrival,omitempty" json:"arrival,omitempty"`
	// External marks the dataset as intentionally produced outside Caesium so
	// the cross-job lint does not demand a producing job.
	External bool `yaml:"external,omitempty" json:"external,omitempty"`
}

type Step struct {
	Name         string            `yaml:"name" json:"name"`
	Type         string            `yaml:"type,omitempty" json:"type,omitempty"`
	Engine       string            `yaml:"engine,omitempty" json:"engine,omitempty"`
	Image        string            `yaml:"image" json:"image"`
	Command      []string          `yaml:"command,omitempty" json:"command,omitempty"`
	NodeSelector map[string]string `yaml:"nodeSelector,omitempty" json:"nodeSelector,omitempty"`
	Next         []string          `yaml:"next,omitempty" json:"next,omitempty"`
	DependsOn    []string          `yaml:"dependsOn,omitempty" json:"dependsOn,omitempty"`
	Retries      int               `yaml:"retries,omitempty" json:"retries,omitempty"`
	RetryDelay   time.Duration     `yaml:"retryDelay,omitempty" json:"retryDelay,omitempty"`
	RetryBackoff bool              `yaml:"retryBackoff,omitempty" json:"retryBackoff,omitempty"`
	TriggerRule  string            `yaml:"triggerRule,omitempty" json:"triggerRule,omitempty"`
	// ReplaySafe marks this step as eligible for quarantined replay. It is
	// control-plane metadata, not a runtime input or cache identity field.
	ReplaySafe                   bool              `yaml:"replaySafe,omitempty" json:"replaySafe,omitempty"`
	VolumeMounts                 []VolumeMount     `yaml:"volumeMounts,omitempty" json:"volumeMounts,omitempty"`
	ServiceAccountName           string            `yaml:"serviceAccountName,omitempty" json:"serviceAccountName,omitempty"`
	PodAnnotations               map[string]string `yaml:"podAnnotations,omitempty" json:"podAnnotations,omitempty"`
	AutomountServiceAccountToken *bool             `yaml:"automountServiceAccountToken,omitempty" json:"automountServiceAccountToken,omitempty"`
	// Kueue delegates this step's admission to a Kueue LocalQueue (kubernetes
	// engine only). It is scheduling metadata and does not affect the cache hash.
	Kueue *Kueue `yaml:"kueue,omitempty" json:"kueue,omitempty"`
	// RateLimit references a job-level shared resource budget for this step.
	// It is scheduling metadata and does not affect the cache hash.
	RateLimit *StepRateLimit `yaml:"rateLimit,omitempty" json:"rateLimit,omitempty"`
	// FanOut materializes N parallel instances from a predecessor's partition
	// marker. Scheduling metadata; excluded from the cache identity hash.
	FanOut *FanOut `yaml:"fanOut,omitempty" json:"fanOut,omitempty"`
	// OutputSchema is a JSON Schema describing this step's expected output keys.
	OutputSchema map[string]any `yaml:"outputSchema,omitempty" json:"outputSchema,omitempty"`
	// InputSchema maps predecessor step names to JSON Schema fragments describing
	// which keys this step requires from each predecessor's output.
	InputSchema map[string]map[string]any `yaml:"inputSchema,omitempty" json:"inputSchema,omitempty"`
	// Datasets declares the datasets this step consumes and produces. It is
	// scheduling metadata for freshness and does not affect the cache hash.
	Datasets       *StepDatasets `yaml:"datasets,omitempty" json:"datasets,omitempty"`
	Cache          any           `yaml:"cache,omitempty" json:"cache"`
	container.Spec `yaml:",inline" json:",inline"`
}

type StepDatasets struct {
	Consumes []ConsumedDataset `yaml:"consumes,omitempty" json:"consumes,omitempty"`
	Produces []ProducedDataset `yaml:"produces,omitempty" json:"produces,omitempty"`
}

type StepRateLimit struct {
	Resource string `yaml:"resource" json:"resource"`
	Units    int    `yaml:"units" json:"units"`
}

type TmpfsSource struct {
	SizeBytes int64 `yaml:"sizeBytes,omitempty" json:"sizeBytes,omitempty"`
	Mode      *int  `yaml:"mode,omitempty" json:"mode,omitempty"`
}

type Trigger struct {
	Type          string            `yaml:"type" json:"type"`
	Configuration map[string]any    `yaml:"configuration" json:"configuration"`
	DefaultParams map[string]string `yaml:"defaultParams,omitempty" json:"defaultParams,omitempty"`
}

type Volume struct {
	Name       string                  `yaml:"name" json:"name"`
	Source     *VolumeSource           `yaml:"source,omitempty" json:"source,omitempty"`
	Sources    map[string]VolumeSource `yaml:"sources,omitempty" json:"sources,omitempty"`
	AccessMode string                  `yaml:"accessMode,omitempty" json:"accessMode,omitempty"`
}

type VolumeMount struct {
	Volume   string `yaml:"volume" json:"volume"`
	Path     string `yaml:"path" json:"path"`
	ReadOnly bool   `yaml:"readOnly,omitempty" json:"readOnly,omitempty"`
	SubPath  string `yaml:"subPath,omitempty" json:"subPath,omitempty"`
}

type VolumeSource struct {
	PVC           string         `yaml:"pvc,omitempty" json:"pvc,omitempty"`
	ClaimTemplate *ClaimTemplate `yaml:"claimTemplate,omitempty" json:"claimTemplate,omitempty"`
	VolumeSource  map[string]any `yaml:"volumeSource,omitempty" json:"volumeSource,omitempty"`
	Bind          string         `yaml:"bind,omitempty" json:"bind,omitempty"`
	Volume        string         `yaml:"volume,omitempty" json:"volume,omitempty"`
	Tmpfs         *TmpfsSource   `yaml:"tmpfs,omitempty" json:"tmpfs,omitempty"`
}

type Watermark struct {
	Key string `yaml:"key,omitempty" json:"key,omitempty"`
}