domain

type AlertRule struct {
	// Type is the channel: "slack" (Slack incoming webhook) or "webhook" (a generic
	// HTTP POST, e.g. PagerDuty/Opsgenie/Teams). Validated by the schema enum.
	Type string `json:"type" yaml:"type"`
	// Conn is the managed Dexaflow connection id holding the endpoint (and secret).
	Conn string `json:"conn" yaml:"conn"`
	// Message is the optional notification body; it is templated at fire time with
	// run context ({{dag}}, {{run_id}}, {{task}}, …). Empty uses a default summary.
	Message string `json:"message,omitempty" yaml:"message,omitempty"`
}

type AlertsConfig struct {
	// OnFailure lists the rules dispatched when a DagRun reaches failed.
	OnFailure []AlertRule `json:"on_failure,omitempty" yaml:"on_failure,omitempty"`
}

type AuditLogEntry struct {
	ID           int64
	When         time.Time
	Action       string
	ResourceType string
	ResourceID   string
	Owner        string
	Extra        string
}

type BuildConfig struct {
	Dockerfile string            `json:"dockerfile,omitempty" yaml:"dockerfile,omitempty"`
	Context    string            `json:"context,omitempty" yaml:"context,omitempty"`
	Platforms  []string          `json:"platforms,omitempty" yaml:"platforms,omitempty"`
	Labels     map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
	// RemoteBuilder is the remote builder for builds no daemonless path
	// covers (ADR 0083); nil leaves those to the target's or workspace's
	// remote_builder, then the local daemon.
	RemoteBuilder *RemoteBuilderConfig `json:"remote_builder,omitempty" yaml:"remote_builder,omitempty"`
	// Args are the build arguments (`--build-arg`) the project's own
	// Dockerfile reads with ARG. Plain values: they stay in the image
	// history, so a secret goes in Secrets.
	Args map[string]string `json:"args,omitempty" yaml:"args,omitempty"`
	// Secrets are the build secrets a RUN line mounts with
	// --mount=type=secret,id=<id>, read from the environment of the build.
	Secrets []BuildSecret `json:"secrets,omitempty" yaml:"secrets,omitempty"`
	// PackageIndex is the Python package index pip and uv install from in
	// place of PyPI; nil is PyPI.
	PackageIndex *PackageIndex `json:"package_index,omitempty" yaml:"package_index,omitempty"`
}

type BuildInfo struct {
	Commit      string `json:"commit,omitempty"`
	Repo        string `json:"repo,omitempty"`
	PipelineURL string `json:"pipeline_url,omitempty"`
	Builder     string `json:"builder,omitempty"`
	BaseImage   string `json:"base_image,omitempty"`
	CLIVersion  string `json:"cli_version,omitempty"`
}

type BuildKitConfig struct {
	// Namespace is the namespace of the builder, the chart's
	// builder.namespace. Required.
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	// PodSelector is the label selector of the builder pod, in equality form
	// (key=value, comma separated); DefaultBuildKitPodSelector when empty.
	PodSelector string `json:"pod_selector,omitempty" yaml:"pod_selector,omitempty"`
	// Context is the kubeconfig context that reaches the builder's cluster;
	// kubectl's current context when empty. Only a local file sets it: a
	// server cannot know the names of a client's contexts.
	Context string `json:"context,omitempty" yaml:"context,omitempty"`
}

type BuildSecret struct {
	// ID is the id a RUN line mounts the secret under.
	ID string `json:"id" yaml:"id"`
	// Env is the environment variable that holds the value.
	Env string `json:"env" yaml:"env"`
}

type CIOIDCDefaults struct {
	// Issuers are the entries of the caller's tenant, in configuration order.
	Issuers []CIOIDCIssuer `json:"issuers"`
}

type CIOIDCIssuer struct {
	// Name is the entry's name in the server configuration.
	Name string `json:"name"`
	// Provider is github, gitlab, cloudbuild or other.
	Provider string `json:"provider"`
	// Issuer is the exact iss of the provider's tokens.
	Issuer string `json:"issuer"`
	// Audience is the aud the pipeline asks its token for.
	Audience string `json:"audience"`
}

type ClearOptions struct {
	ResetDagRun        bool
	RunOnLatestVersion bool
}

type ClearVersionKept struct {
	RunID  string
	Reason string
}

type CloudBuildConfig struct {
	// Project is the Google Cloud project the build runs in. Required.
	Project string `json:"project,omitempty" yaml:"project,omitempty"`
	// Region is the Cloud Build region, such as us-central1; gcloud's
	// builds/region, else global, when empty.
	Region string `json:"region,omitempty" yaml:"region,omitempty"`
	// WorkerPool is a private pool,
	// projects/<project>/locations/<region>/workerPools/<name>.
	WorkerPool string `json:"worker_pool,omitempty" yaml:"worker_pool,omitempty"`
	// ServiceAccount is the account the build runs as,
	// projects/<project>/serviceAccounts/<email>.
	ServiceAccount string `json:"service_account,omitempty" yaml:"service_account,omitempty"`
}

type ConfigDefaults struct {
	Retries                 int `json:"retries,omitempty" yaml:"retries,omitempty"`
	RetryDelaySeconds       int `json:"retry_delay_seconds,omitempty" yaml:"retry_delay_seconds,omitempty"`
	ExecutionTimeoutSeconds int `json:"execution_timeout_seconds,omitempty" yaml:"execution_timeout_seconds,omitempty"`
	// Size is the default pool_slots of every task that sets none, in dag.py or
	// in tasks.<id>.size (ADR 0066).
	Size      *int              `json:"size,omitempty" yaml:"size,omitempty"`
	Resources *DefaultResources `json:"resources,omitempty" yaml:"resources,omitempty"`
	// NodeSelector is the DAG-wide pod placement fallback applied to every task
	// that declares no execution.node_selector of its own. Like Resources it is a
	// default, so the most-specific per-task value always wins. Consumed at
	// compile time by the overlay, which bakes it onto each task in dag.json.
	NodeSelector map[string]string `json:"node_selector,omitempty" yaml:"node_selector,omitempty"`
}

type Connection struct {
	ConnID      string
	ConnType    string
	Host        string
	Schema      string
	Login       string
	Password    string
	Port        *int
	Extra       string
	Description string
	// ExtraUnreadable reports a stored extra that no configured secret key
	// opens (the key was rotated without keeping the old one, for example).
	// Extra is empty then. Only listings set it; reading the connection alone
	// is an ErrValueUnreadable error (#1677).
	ExtraUnreadable bool
}

type ConnectionPatch struct {
	ConnID      string
	ConnType    string
	Host        *string
	Schema      *string
	Login       *string
	Password    *string
	Port        *int
	Extra       *string
	Description *string
}

type CurrentVersionChange struct {
	From    DagVersion
	To      DagVersion
	Changed bool
}

type DAG struct {
	DagID          string
	Description    string
	Owner          string
	Tags           []string
	Schedule       *string
	ScheduleTZ     string
	StartDate      *time.Time
	IsPaused       bool
	IsActive       bool
	MaxActiveRuns  int
	Catchup        bool
	LastParsedTime *time.Time
	// CurrentVersion is the LABEL of the DAG's current registered version, empty
	// when it cannot be resolved. Paired with DagRun.Version by the UI's clear
	// dialog, which offers "Run with latest bundle version" only when the two
	// differ — see that field.
	CurrentVersion string
}

type DAGSpec struct {
	SchemaVersion string   `json:"schema_version"`
	DagID         string   `json:"dag_id"`
	DagVersion    string   `json:"dag_version"`
	Image         string   `json:"image"`
	Description   string   `json:"description,omitempty"`
	Owner         string   `json:"owner,omitempty"`
	Tags          []string `json:"tags,omitempty"`
	Schedule      *string  `json:"schedule,omitempty"`
	ScheduleTZ    string   `json:"schedule_timezone,omitempty"`
	StartDate     string   `json:"start_date,omitempty"`
	EndDate       *string  `json:"end_date,omitempty"`
	MaxActiveRuns int      `json:"max_active_runs,omitempty"`
	// MaxActiveTasks caps how many of this DAG's task instances may be
	// concurrently non-terminal (queued or running) across all of its active
	// runs — Airflow's per-DAG max_active_tasks (ADR 0053 Stage 1). Zero (the
	// default) means unlimited: a DAG that never sets it, and all of Lite, plans
	// exactly as before. The scheduler enforces it in PlanRun's scheduled→queued
	// admission gate.
	MaxActiveTasks int `json:"max_active_tasks,omitempty"`
	// MinIdleWorkers is the number of idle warm workers the author asks to keep
	// for this DAG version so its tasks skip the cold pod start (ADR 0058, warm
	// pools model A2). It comes from min_idle_workers in dexaflow.yaml, which
	// the compiler overlays onto dag.json. The operator gates whether warmth
	// happens at all (execution.warm_pools_enabled) and caps it
	// (config.ExecutionSection.EffectiveMinIdle clamps it to max_pool_size);
	// whether a pod may be reused across attempts stays the operator's security
	// decision. A version whose DAG declares it is prewarmed when it becomes
	// current (ADR 0082). Zero, the default, declares none.
	MinIdleWorkers int  `json:"min_idle_workers,omitempty"`
	Catchup        bool `json:"catchup,omitempty"`
	// IsPausedUponCreation is Airflow's is_paused_upon_creation DAG argument:
	// whether the DAG starts paused when it is registered for the first time.
	// It overrides the server's dags_are_paused_at_creation; nil leaves the
	// decision to that setting. It is read only on creation: a later version
	// never changes whether the DAG is paused (#1705).
	IsPausedUponCreation *bool        `json:"is_paused_upon_creation,omitempty"`
	DefaultArgs          *DefaultArgs `json:"default_args,omitempty"`
	// Staging, when enabled, requests an ephemeral RWX volume shared by the run's
	// tasks at /staging (ADR 0022). nil/disabled means no staging volume.
	Staging *StagingConfig `json:"staging,omitempty"`
	// Alerts declares native on-failure alerting (#424), overlaid from dexaflow.yaml
	// at compile time so the scheduler fires it from the artifact without re-reading
	// the project config. nil means no alerting.
	Alerts *AlertsConfig `json:"alerts,omitempty"`
	// Variables and Connections are the secret names this DAG declares (ADR 0045,
	// ADR 0055). A task receives a variable or connection only if the DAG declared
	// it; TaskSpec may narrow the set further per task. Absent (empty) is always
	// valid and means the DAG declares nothing — the additive, back-compatible
	// default. These carry the declaration only; secret delivery still ships the
	// whole tenant vault until enforcement lands on a later increment.
	Variables   []string `json:"variables,omitempty"`
	Connections []string `json:"connections,omitempty"`
	// Params are the DAG's author-declared run parameters (Airflow's params=),
	// keyed by name. Each carries a Default (materialized into a run's conf when
	// the trigger omits that key) and an optional JSON Schema the trigger-time
	// conf value is validated against. Absent (empty) means the DAG declares no
	// params — the additive, back-compatible default, so the compiled shape of a
	// param-free DAG is unchanged. Part of the immutable spec (CanonicalHash), so
	// changing a default or schema produces a new DAG version.
	Params map[string]ParamSpec `json:"params,omitempty"`
	Tasks  []TaskSpec           `json:"tasks"`
	// Source is the original dag.py text, captured at compile time so the UI's
	// Code tab can show the Python a human wrote (not the compiled spec). It is
	// part of the artifact: changing it produces a new version.
	Source string `json:"source,omitempty"`
}

type DagFilter struct {
	DagIDPattern                string
	DagIDPrefixPattern          string
	DagDisplayNamePattern       string
	DagDisplayNamePrefixPattern string
	Paused                      *bool
	LastDagRunState             string
	Tags                        []string
	TagsMatchMode               string // "any" or "all"
	Owners                      []string
	IsFavorite                  *bool
	UserID                      string
	OrderBy                     string
	Limit                       int
	Offset                      int
}

type DagPromotion struct {
	Target string
	Server string
}

type DagRegistered struct {
	Created    bool
	DagCreated bool
	IsPaused   bool
}

type DagRegistration struct {
	Spec          DAGSpec
	SpecHash      string
	ActorUserID   string
	IsPaused      *bool
	DryRun        bool
	PromotedFrom  *DagPromotion
	BuildInfo     *BuildInfo
	RequireDigest DigestRequirement
}

type DagRun struct {
	DagID       string
	RunID       string
	LogicalDate time.Time
	State       DagRunState
	RunType     string
	QueuedAt    time.Time
	StartedAt   *time.Time
	EndedAt     *time.Time
	Note        string
	// Conf is the run's configuration as a JSON object, supplied at trigger time
	// and exposed to tasks as params. Empty means no configuration; storage
	// persists the empty-object default so downstream readers never see NULL.
	Conf json.RawMessage
	// Version is the LABEL of the dag_version this run is pinned to (the
	// `dag_version` from its dag.json), empty when it cannot be resolved.
	//
	// It exists for the UI: the SPA's clear dialog renders its "Run with latest
	// bundle version" control only when the run's bundle_version differs from the
	// DAG's, and hides it when either is null. With no label the operator cannot
	// ask for the current version at all, whatever the API accepts.
	Version string
}

type DagRunFilter struct {
	RunIDPattern       string
	RunIDPrefixPattern string
	RunType            string
	States             []string
	StartDateGte       *time.Time
	StartDateLte       *time.Time
	EndDateGte         *time.Time
	EndDateLte         *time.Time
	Limit              int
	Offset             int
}

type DagRunState string

type DagSetCurrent struct {
	DagID         string
	Selector      DagVersionSelector
	ActorUserID   string
	Admit         func(DAGSpec) error
	RequireDigest DigestRequirement
}

type DagStats struct {
	Active  int
	Failed  int
	Running int
	Queued  int
}

type DagVersion struct {
	ID            string
	VersionNumber int
	CreatedAt     time.Time
	// Version is the deployment label that produced this snapshot: by default a
	// git describe (tag/SHA) plus a content hash in production, or
	// "dev-<timestamp>" in Lite. It is the stable
	// per-deployment identifier under a stable dag_id.
	Version string
	// ImageReference is the image the version runs, pinned by digest when the
	// deploy resolved one.
	ImageReference string
	// SpecHash is the canonical hash of the version's dag.json.
	SpecHash string
	// IsCurrent reports whether this is the DAG's current version: the one new
	// runs are created with.
	IsCurrent bool
	// CreatedBy is the id of the user who registered the version, or "" when
	// the register had no user of the tenant (Lite's dev principal, a direct
	// call, a deleted user). It is an id, not an email: every reader of the
	// DAG sees it.
	CreatedBy string
	// BuildInfo is where the version was built, as its register sent it
	// (#1702); nil when it sent none.
	BuildInfo *BuildInfo
}

type DagVersionSelector struct {
	Version string
	Number  int
}

type DbtConfig struct {
	// Project is the directory containing dbt_project.yml.
	Project string `json:"project,omitempty" yaml:"project,omitempty"`
	// Granularity is the task partition strategy: node, level or folder (ADR 0042
	// §5). Empty means node. Tag and selector grouping are not implemented — the
	// schema enum is the three above; see #398.
	Granularity string `json:"granularity,omitempty" yaml:"granularity,omitempty"`
	// Manifest optionally points to a pre-built manifest.json (the Pro/CI baked
	// path); empty means run `dbt parse` to generate it at compile time.
	Manifest string `json:"manifest,omitempty" yaml:"manifest,omitempty"`
	// Schedule is the DAG's cron expression or preset (e.g. "@daily",
	// "0 6 * * *"). dbt carries no schedule, so it is declared here; empty means
	// an unscheduled DAG (run on demand).
	Schedule string `json:"schedule,omitempty" yaml:"schedule,omitempty"`
	// Connection is a managed Dexaflow connection id (ADR 0043 #2). When set, the
	// dbt task generates its profiles.yml from the connection delivered to the pod
	// instead of a profiles.yml baked into the image — use one or the other.
	Connection string `json:"connection,omitempty" yaml:"connection,omitempty"`
	// Schema overrides the dbt target schema in the generated profile (where models
	// materialize); empty uses the connection's or dbt's default.
	Schema string `json:"schema,omitempty" yaml:"schema,omitempty"`
}

type DefaultArgs struct {
	Retries                 int `json:"retries,omitempty"`
	RetryDelaySeconds       int `json:"retry_delay_seconds,omitempty"`
	ExecutionTimeoutSeconds int `json:"execution_timeout_seconds,omitempty"`
}

type DefaultLimits struct {
	// contains filtered or unexported fields
}

type DefaultResources struct {
	CPU    string `json:"cpu,omitempty" yaml:"cpu,omitempty"`
	Memory string `json:"memory,omitempty" yaml:"memory,omitempty"`
}

type DeployDefaults struct {
	// Registry is the image prefix a project without registry.url pushes
	// to, such as ghcr.io/acme. The image name defaults to the dag_id.
	Registry string `json:"registry" mapstructure:"registry"`
	// Platforms replaces build.platforms for projects that set none.
	Platforms []string `json:"platforms" mapstructure:"platforms"`
	// BaseImage replaces base_image for projects that set none.
	BaseImage string `json:"base_image" mapstructure:"base_image"`
	// SourceModeImage is the runtime image a deploy registers a DAG's
	// dag.py on, with no build, when nothing local names one (source mode,
	// ADR 0067, #1772). The server fills it from execution.source_mode.image
	// when deploy.defaults.source_mode is on; it is never set by hand, so
	// it cannot drift from the image the server runs.
	SourceModeImage string `json:"source_mode_image" mapstructure:"-"`
	// RemoteBuilder replaces build.remote_builder for projects, targets and
	// workspaces that set none (ADR 0083, #1890); nil advertises none. The
	// server fills it from deploy.defaults.remote_builder.
	RemoteBuilder *RemoteBuilderConfig `json:"remote_builder" mapstructure:"-"`
	// TaskServiceAccount is the ServiceAccount task pods run as when a task
	// sets no execution.service_account (#1890). The server fills it from
	// executor.task_service_account when deploy.defaults.task_service_account
	// is on, so it cannot drift from the account pods get; a deploy reports
	// it and never writes it into dag.json.
	TaskServiceAccount string `json:"task_service_account" mapstructure:"-"`
	// WarmPools is what the cluster does with a DAG's min_idle_workers
	// (ADR 0058, ADR 0082, #1890); nil advertises nothing. The server fills
	// it from execution.* when deploy.defaults.warm_pools is on.
	WarmPools *WarmPoolDefaults `json:"warm_pools" mapstructure:"-"`
	// CIOIDC lists the CI OIDC issuers of the caller's tenant (ADR 0092),
	// so `dexaflow ci init` writes a pipeline that deploys without a stored
	// token; nil when the tenant has none. Unlike the fields above it
	// depends on the caller: the server fills it per request, and it is no
	// deploy setting, so IsEmpty and Validate ignore it.
	CIOIDC *CIOIDCDefaults `json:"ci_oidc" mapstructure:"-"`
}

type DigestRequirement string

type Execution struct {
	NodeSelector    map[string]string `json:"node_selector,omitempty" yaml:"node_selector,omitempty"`
	Tolerations     []map[string]any  `json:"tolerations,omitempty" yaml:"tolerations,omitempty"`
	ServiceAccount  string            `json:"service_account,omitempty" yaml:"service_account,omitempty"`
	ImagePullPolicy string            `json:"image_pull_policy,omitempty" yaml:"image_pull_policy,omitempty"`

	// PriorityClassName ranks this task pod against its neighbors on a shared
	// cluster; the named PriorityClass is a platform-owned, cluster-scoped object,
	// so under genuine contention the scheduler preempts Dexaflow's ETL rather than
	// production services (ADR 0054).
	PriorityClassName string `json:"priority_class_name,omitempty" yaml:"priority_class_name,omitempty"`
	// TerminationGracePeriodSeconds is how long the pod is given to shut down after
	// a delete/preempt before SIGKILL. Nil leaves the cluster default (30s).
	TerminationGracePeriodSeconds *int64 `json:"termination_grace_period_seconds,omitempty" yaml:"termination_grace_period_seconds,omitempty"`
	// RuntimeClassName selects an alternate container runtime (e.g. a sandboxed or
	// GPU runtime) registered as a RuntimeClass. Nil uses the cluster default.
	RuntimeClassName *string `json:"runtime_class_name,omitempty" yaml:"runtime_class_name,omitempty"`
	// TopologySpreadConstraints spread a DAG's task pods across failure domains
	// (zones, nodes). Untyped []map[string]any carried verbatim from the DAG spec;
	// the executor round-trips it to []corev1.TopologySpreadConstraint.
	TopologySpreadConstraints []map[string]any `json:"topology_spread_constraints,omitempty" yaml:"topology_spread_constraints,omitempty"`
	// Affinity pins or repels a task pod relative to nodes and other pods
	// (node/pod affinity and anti-affinity). Untyped map[string]any carried verbatim
	// from the DAG spec; the executor round-trips it to *corev1.Affinity.
	Affinity map[string]any `json:"affinity,omitempty" yaml:"affinity,omitempty"`
	// ResourceClaims declares the pod-level ResourceClaims (Dynamic Resource
	// Allocation, GA in Kubernetes 1.34) an accelerator DAG needs — e.g. a GPU from
	// a claim template. Untyped []map[string]any carried verbatim from the DAG spec;
	// the executor round-trips it to []corev1.PodResourceClaim. A container consumes
	// one by naming it in Resources.Claims.
	ResourceClaims []map[string]any `json:"resource_claims,omitempty" yaml:"resource_claims,omitempty"`
	// Labels and Annotations are operator-declared pod metadata merged onto the task
	// pod. Keys under ReservedMetadataPrefix belong to Dexaflow (the reconciler,
	// terminate path, warm-pool reconciler and token exchange select on them), so
	// Validate refuses them and the executor drops any that still arrive.
	Labels      map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
	Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty"`
}

type ExecutionMode string

type ExecutionPolicy struct {
	// contains filtered or unexported fields
}

type ExecutionPolicyConfig struct {
	// Fields lists the governed fields a DAG author may set. Unset (nil) or "*"
	// allows every one; "none" or an explicitly empty list allows none.
	Fields []string
	// PriorityClasses, when not empty, lists the only values a task's
	// priority_class_name may take.
	PriorityClasses []string
	// ServiceAccounts, when not empty, lists the only execution.service_account
	// values a task may name (issue #537 C2). A task that names none runs as the
	// operator's default task ServiceAccount and is not checked.
	ServiceAccounts []string
	// Images, when not empty, lists the DAG images that may run (issue #537
	// C2): an exact image reference, or a prefix ending in "*" (for example
	// "registry.example.com/team-a/*"). A lone "*" allows any image.
	Images []string
}

type HistoricalMetrics struct {
	RunStates map[string]int
	TIStates  map[string]int
}

type ImportError struct {
	// ID is the stable identifier of the error record.
	ID string
	// Filename is the DAG source path that failed to import.
	Filename string
	// StackTrace is the human-readable parse/compile error (traceback).
	StackTrace string
	// BundleName is the originating bundle (empty when unknown).
	BundleName string
	// Timestamp is when the error was recorded.
	Timestamp time.Time
}

type LeoflowConfig struct {
	SchemaVersion string   `json:"schema_version,omitempty" yaml:"schema_version,omitempty"`
	DagID         string   `json:"dag_id" yaml:"dag_id"`
	Description   string   `json:"description,omitempty" yaml:"description,omitempty"`
	Owner         string   `json:"owner,omitempty" yaml:"owner,omitempty"`
	Tags          []string `json:"tags,omitempty" yaml:"tags,omitempty"`
	PythonVersion string   `json:"python_version,omitempty" yaml:"python_version,omitempty"`
	// PythonVersionDefaulted reports that ApplyDefaults supplied PythonVersion
	// because the config declared none. It is not part of the authoring surface
	// and never serialized — it exists so a consumer can tell "the author chose
	// 3.11" from "nobody said anything", which are the same string afterwards.
	// `dexaflow lite` needs the distinction: enforcing a version the CLI invented
	// refuses to boot over a choice the user never made (#1092 follow-up).
	PythonVersionDefaulted bool     `json:"-" yaml:"-"`
	BaseImage              string   `json:"base_image,omitempty" yaml:"base_image,omitempty"`
	Dependencies           []string `json:"dependencies,omitempty" yaml:"dependencies,omitempty"`
	Connectors             []string `json:"connectors,omitempty" yaml:"connectors,omitempty"`
	// Connections and Variables are the per-DAG declared secret sets (ADR 0045,
	// ADR 0055). Carried verbatim to the parser, which emits them into dag.json.
	// Distinct from Connectors (pip provider packages, ADR 0038) — a different key
	// one letter away. Empty declares nothing.
	Connections    []string        `json:"connections,omitempty" yaml:"connections,omitempty"`
	Variables      []string        `json:"variables,omitempty" yaml:"variables,omitempty"`
	SystemPackages []string        `json:"system_packages,omitempty" yaml:"system_packages,omitempty"`
	DagSource      string          `json:"dag_source,omitempty" yaml:"dag_source,omitempty"`
	IncludePaths   []string        `json:"include_paths,omitempty" yaml:"include_paths,omitempty"`
	ExcludePaths   []string        `json:"exclude_paths,omitempty" yaml:"exclude_paths,omitempty"`
	Build          *BuildConfig    `json:"build,omitempty" yaml:"build,omitempty"`
	Registry       *RegistryConfig `json:"registry,omitempty" yaml:"registry,omitempty"`
	Defaults       *ConfigDefaults `json:"defaults,omitempty" yaml:"defaults,omitempty"`
	// Staging requests the opt-in per-DAG-run shared volume (ADR 0022). It is a
	// Dexaflow deployment concern (not an Airflow DAG attribute), so it lives in
	// dexaflow.yaml and the compiler overlays it onto the produced dag.json.
	Staging *StagingConfig `json:"staging,omitempty" yaml:"staging,omitempty"`
	// Dbt declares a dbt project as the DAG source (ADR 0042). Its presence routes
	// `dexaflow compile` to the dbt renderer instead of the Python parser.
	Dbt *DbtConfig `json:"dbt,omitempty" yaml:"dbt,omitempty"`
	// DbtGroups configures dbt projects embedded as task groups in a dag.py (ADR
	// 0043), keyed by the name passed to `dbt_group(name)`. Schedule does not apply
	// to a group (the DAG owns the schedule).
	DbtGroups map[string]*DbtConfig `json:"dbt_groups,omitempty" yaml:"dbt_groups,omitempty"`
	// Tasks holds per-task overrides bound by task_id (ADR 0023). Each entry's
	// key must match a task_id in the compiled DAG; the compiler errors on an
	// unknown id rather than silently dropping it.
	Tasks map[string]*TaskConfig `json:"tasks,omitempty" yaml:"tasks,omitempty"`
	// Alerts declares native on-failure alerting (#424): the scheduler fires the
	// listed rules when a DagRun reaches the terminal failed state, in Go, with no
	// task pod and no Python in the hot path. A Dexaflow deployment concern (not an
	// Airflow DAG attribute), so it lives in dexaflow.yaml and the compiler overlays
	// it onto the produced dag.json.
	Alerts *AlertsConfig `json:"alerts,omitempty" yaml:"alerts,omitempty"`
	// MinIdleWorkers is the number of idle warm workers the DAG asks to keep
	// for its current version (ADR 0058, ADR 0082): with warm pools on, an
	// unpaused DAG that declares it is prewarmed from the moment a version
	// becomes current. The compiler overlays it onto dag.json; the server
	// clamps it to execution.max_pool_size, and with warm pools off it does
	// nothing. Zero declares none.
	MinIdleWorkers int `json:"min_idle_workers,omitempty" yaml:"min_idle_workers,omitempty"`
}

type PackageIndex struct {
	// URL is the index's simple API, such as https://pypi.example.com/simple.
	URL string `json:"url" yaml:"url"`
	// UsernameEnv is the environment variable holding the user name.
	UsernameEnv string `json:"username_env,omitempty" yaml:"username_env,omitempty"`
	// PasswordEnv is the environment variable holding the password or token.
	PasswordEnv string `json:"password_env,omitempty" yaml:"password_env,omitempty"`
}

type PageCursor struct {
	At    time.Time
	Key   string
	Total int
}

type ParamSpec struct {
	// Default is the value merged into a run's conf when the trigger omits this
	// key. Absent (omitempty, len 0) means the param is REQUIRED — the trigger
	// must supply it — as distinct from an explicit JSON null default.
	Default json.RawMessage `json:"default,omitempty"`
	Schema  json.RawMessage `json:"schema,omitempty"`
}

type Pool struct {
	Name        string
	Slots       int
	Description string
	IsDefault   bool
}

type PoolUsage struct {
	Running   int
	Queued    int
	Scheduled int
	Deferred  int
}

type PythonDeprecation struct {
	// Version is the deprecated python_version value, e.g. "3.10".
	Version string `json:"-"`
	// EOL is the upstream CPython end-of-life date (YYYY-MM-DD). After it,
	// docker-library/python stops rebuilding the line and the base image stops
	// receiving OS security updates.
	EOL string `json:"eol"`
	// RemoveAfter is the date after which the release stops publishing a base
	// image for this line (YYYY-MM-DD).
	RemoveAfter string `json:"remove_after"`
	// Replacement is the version an author should move to.
	Replacement string `json:"replacement"`
	// Reason is the human-readable justification, quoted verbatim in the CLI
	// warning so the author gets the argument and not just a verdict.
	Reason string `json:"reason"`
}

type RegistryConfig struct {
	URL string `json:"url,omitempty" yaml:"url,omitempty"`
	// AuthMethod is where the CLI reads the registry credential: auto (the
	// default), docker_config or cloud; env and iam still load, deprecated
	// (build.ParseAuthMethod, ADR 0080).
	AuthMethod  string `json:"auth_method,omitempty" yaml:"auth_method,omitempty"`
	ImageName   string `json:"image_name,omitempty" yaml:"image_name,omitempty"`
	TagStrategy string `json:"tag_strategy,omitempty" yaml:"tag_strategy,omitempty"`
}

type RemoteBuilderConfig struct {
	// CloudBuild builds on Google Cloud Build through the gcloud CLI.
	CloudBuild *CloudBuildConfig `json:"cloud_build,omitempty" yaml:"cloud_build,omitempty"`
	// BuildKit builds on the in-cluster BuildKit daemon the Helm chart runs
	// (builder.enabled), through buildctl and kubectl.
	BuildKit *BuildKitConfig `json:"buildkit,omitempty" yaml:"buildkit,omitempty"`
}

type ResourceQuantity struct {
	CPU    string `json:"cpu,omitempty" yaml:"cpu,omitempty"`
	Memory string `json:"memory,omitempty" yaml:"memory,omitempty"`
	// EphemeralStorage bounds the node-local scratch (writable layer, emptyDir,
	// logs) a task may use. Setting it keeps a runaway task from filling a shared
	// node's disk and evicting its neighbors under disk pressure (ADR 0054).
	// Kubernetes quantity, e.g. "2Gi".
	EphemeralStorage string `json:"ephemeral_storage,omitempty" yaml:"ephemeral_storage,omitempty"`
}

type ResourceUnit struct {
	// contains filtered or unexported fields
}

type ResourceUnitConfig struct {
	CPU     string
	Memory  string
	Enforce string // "" means UnitEnforceRefuse
	MaxSize int    // 0 means DefaultUnitMaxSize
}

type Resources struct {
	Requests *ResourceQuantity `json:"requests,omitempty" yaml:"requests,omitempty"`
	Limits   *ResourceQuantity `json:"limits,omitempty" yaml:"limits,omitempty"`
	// Claims lists the ResourceClaims (declared in Execution.ResourceClaims) this
	// task's container consumes — the container half of Dynamic Resource Allocation
	// (DRA, GA in Kubernetes 1.34). Untyped []map[string]any carried verbatim from
	// the DAG spec; the executor round-trips it to []corev1.ResourceClaim. Each
	// entry names a claim (and optionally a specific request within it) that makes
	// an accelerator available inside the container.
	Claims []map[string]any `json:"claims,omitempty" yaml:"claims,omitempty"`
}

type SafeError struct {
	// Message is the client-facing phrase, without the class's own wording.
	Message string
	// Class is the sentinel this failure belongs to (ErrValidation,
	// ErrConflict, ErrNotFound, ...). errors.Is sees it through Unwrap.
	Class error
}

type StagingConfig struct {
	Enabled      bool   `json:"enabled" yaml:"enabled"`
	Size         string `json:"size,omitempty" yaml:"size,omitempty"`
	StorageClass string `json:"storage_class,omitempty" yaml:"storage_class,omitempty"`
}

type StagingVolumeState struct {
	// PVCName is the staging PersistentVolumeClaim's name.
	PVCName string
	// RunState is the DAG run's state ("success", "failed", "running", …), or
	// empty when the run no longer exists.
	RunState string
	// RunEndedAt is when the run reached a terminal state, if known.
	RunEndedAt *time.Time
	// CreatedAt is when the volume was provisioned. The GC never deletes a volume
	// younger than the TTL when its run cannot be resolved, so a lookup miss can
	// never reclaim an active run's fresh volume.
	CreatedAt time.Time
}

type SuspensionMode string

type TaskConfig struct {
	Retries                 *int              `json:"retries,omitempty" yaml:"retries,omitempty"`
	RetryDelaySeconds       *int              `json:"retry_delay_seconds,omitempty" yaml:"retry_delay_seconds,omitempty"`
	ExecutionTimeoutSeconds *int              `json:"execution_timeout_seconds,omitempty" yaml:"execution_timeout_seconds,omitempty"`
	Env                     map[string]string `json:"env,omitempty" yaml:"env,omitempty"`
	// Connections and Variables narrow the DAG-level declared secret set to this
	// task (ADR 0045 §Settled #1, ADR 0055). Empty means the task inherits the
	// DAG-level declaration.
	Connections []string   `json:"connections,omitempty" yaml:"connections,omitempty"`
	Variables   []string   `json:"variables,omitempty" yaml:"variables,omitempty"`
	Resources   *Resources `json:"resources,omitempty" yaml:"resources,omitempty"`
	Execution   *Execution `json:"execution,omitempty" yaml:"execution,omitempty"`
	// Size is the task's pool_slots (ADR 0066): how many slots of its pool it
	// takes while queued or running. It overrides pool_slots from dag.py.
	Size *int `json:"size,omitempty" yaml:"size,omitempty"`
}

type TaskInstance struct {
	DagID     string
	RunID     string
	TaskID    string
	MapIndex  int
	TryNumber int
	MaxTries  int
	State     TaskState
	Operator  string
	// ScheduledAt and QueuedAt record when the instance first entered the
	// scheduled and queued states (Airflow's scheduled_when / queued_when).
	ScheduledAt *time.Time
	QueuedAt    *time.Time
	StartedAt   *time.Time
	EndedAt     *time.Time
	Duration    *float64
	Hostname    string
	// Note is operational context shown in the UI's task panel — e.g. why a task
	// is queued but not running (no executor available).
	Note string
	// Pool is the pool the instance is charged to, "default_pool" when the task
	// declares none, and PoolSlots the slots the admission gate charges it (ADR
	// 0066). Both are the instance's own: a clear re-binds them from the version
	// the re-run executes (#1589).
	Pool      string
	PoolSlots int
	// FailureReason is a short, human-readable cause for a terminal failure,
	// recorded by whichever component observed it: the agent's own report, the
	// reconciler reading the pod (image pull, OOM, exit code), a reaper declaring
	// the pod or agent lost, or the agent's pre-registration classification. It is
	// the answer to "why did this fail?" for an attempt that streamed no logs
	// because its agent never started — the case where the only remaining source
	// of truth used to be `kubectl logs` against the cluster.
	//
	// It is best-effort and often empty: a healthy instance has none, and a cause
	// nobody observed cannot be invented. It carries a classification, never a
	// credential or a raw internal error.
	FailureReason string
}

type TaskInstanceFilter struct {
	States              []string
	TaskIDPattern       string
	TaskIDPrefixPattern string
	Pool                string
	Limit               int
	Offset              int
}

type TaskSpec struct {
	TaskID      string      `json:"task_id"`
	Type        TaskType    `json:"type"`
	DependsOn   []string    `json:"depends_on,omitempty"`
	TriggerRule TriggerRule `json:"trigger_rule,omitempty"`
	// Pool is the named task pool this task draws a slot from (Airflow's `pool`),
	// the cross-DAG concurrency budget admission enforces (ADR 0053 Stage 3). Empty
	// (the default) means the implicit default_pool, so every task is always in a
	// well-defined pool. The pool gate is Pro-only; Lite ignores this field, so a
	// DAG that sets it plans identically on Lite.
	Pool string `json:"pool,omitempty"`
	// PoolSlots is how many slots of its pool the task takes while it is queued
	// or running (Airflow's pool_slots, ADR 0066). Zero means 1, so a DAG that
	// never sets it weighs exactly what it did before. dexaflow.yaml sets it as
	// `size`. Ignored where Pool is (Lite).
	PoolSlots               int               `json:"pool_slots,omitempty"`
	Retries                 *int              `json:"retries,omitempty"`
	RetryDelaySeconds       *int              `json:"retry_delay_seconds,omitempty"`
	ExecutionTimeoutSeconds *int              `json:"execution_timeout_seconds,omitempty"`
	ExecutionMode           ExecutionMode     `json:"execution_mode,omitempty"`
	Entrypoint              string            `json:"entrypoint,omitempty"`
	Env                     map[string]string `json:"env,omitempty"`
	// Variables and Connections narrow the DAG's declared secret set to this task
	// (ADR 0045 §Settled #1, ADR 0055). Absent (empty) means the task inherits the
	// DAG-level declaration. Carries the declaration only; delivery is unchanged.
	Variables   []string            `json:"variables,omitempty"`
	Connections []string            `json:"connections,omitempty"`
	Resources   *Resources          `json:"resources,omitempty"`
	Execution   *Execution          `json:"execution,omitempty"`
	XComInput   map[string][]string `json:"xcom_input,omitempty"`
	XComSchema  map[string]any      `json:"xcom_schema,omitempty"`
	// CallArgs carries TaskFlow literal call arguments captured at compile time
	// (#115). The agent serializes the whole map as a single env var
	// LEOFLOW_CALL_ARGS_JSON; the runtime decodes and delivers each value to
	// the user function. XCom upstreams take precedence at runtime over a
	// same-name literal (the deterministic merge owned by leoflow_runtime).
	// Named call_args (not params) to leave the term free for Airflow's
	// DAG-run params semantic (#148).
	CallArgs map[string]any `json:"call_args,omitempty"`
	// Params are a bash or python task's own params (Airflow's task-level
	// params=), captured at compile time (#1843). RunParams layers them over the
	// DAG's param defaults and under the run conf. A captured operator carries
	// its params in OperatorArgs instead.
	Params map[string]any `json:"params,omitempty"`
	// OperatorClass is the dotted Airflow operator/sensor class for an
	// airflow_operator task (ADR 0040), e.g.
	// "airflow.providers.snowflake.operators.snowflake.SQLExecuteQueryOperator".
	OperatorClass string `json:"operator_class,omitempty"`
	// OperatorArgs are the operator's constructor kwargs captured at compile time.
	// The agent serializes them as the env var LEOFLOW_OPERATOR_ARGS; the runtime
	// instantiates the operator with them.
	OperatorArgs map[string]any `json:"operator_args,omitempty"`
	// OnFailureCallback marks that the task declares an Airflow on_failure_callback
	// (#424). The callable itself is not carried (it can't be serialized); the
	// runtime re-imports dag.py and runs it in the task process on failure. The
	// flag lets the agent/UI know a callback will run without importing user code.
	OnFailureCallback bool `json:"on_failure_callback,omitempty"`
}

type TaskState string

type TaskType string

type TenantLimits struct {
	// MaxDags caps how many DAGs the tenant may register. New versions of a DAG
	// it already has are always accepted.
	MaxDags int
	// MaxRunsPerDay caps how many DAG runs, manual and scheduled alike, the
	// tenant may create in one UTC calendar day.
	MaxRunsPerDay int
	// MinScheduleIntervalSeconds is the shortest gap, in seconds, a DAG's
	// schedule may leave between two consecutive runs (MinScheduleInterval).
	MinScheduleIntervalSeconds int
	// MaxTaskPoolSlots caps a task's pool_slots (its size, ADR 0066): a DAG
	// with a larger task is refused at registration.
	MaxTaskPoolSlots int
}

type TenantLimitsUpdate struct {
	MaxDags                    *int
	MaxRunsPerDay              *int
	MinScheduleIntervalSeconds *int
	MaxTaskPoolSlots           *int
}

type TenantSuspension struct {
	Mode   SuspensionMode
	Reason string
	// Since is when the tenant was first suspended; changing the reason of a
	// suspension in place keeps it.
	Since time.Time
}

type TriggerRule string

type UnitMisfitError struct {
	TaskID  string
	Size    int // the task's pool_slots
	Need    int // the size its resources need; 0 when over max_size
	MaxSize int // set when the task is over executor.unit.max_size
	// contains filtered or unexported fields
}

type UsageCursor struct {
	Xid uint64
	ID  int64
}

type UsageEvent struct {
	Cursor UsageCursor
	// Tenant, DagID and RunID are resolved when the event is served; they are
	// empty once the tenant or the run is deleted.
	Tenant         string
	DagID, RunID   string
	TaskInstanceID string
	TaskID         string
	MapIndex       int
	TryNumber      int
	AttemptEpoch   int
	Revision       int
	State          TaskState
	PreviousState  TaskState
	PoolSlots      int
	// StartedAt and EndedAt are nil for a task that never started (skipped,
	// upstream failed). EndedAt is the task's end time, or the time of the
	// change that ended the attempt when the task has none.
	StartedAt, EndedAt *time.Time
	LastFailureKind    string
	RecordedAt         time.Time
}

type UsagePage struct {
	// Enabled is false when recording is off; nothing else is set then.
	Enabled bool
	// Gone reports that the retention janitor deleted events after the
	// cursor; Oldest is then the first cursor whose following events are
	// complete, and Events is empty.
	Gone   bool
	Oldest UsageCursor
	Events []UsageEvent
}

type User struct {
	ID        string
	Email     string
	Roles     []string
	IsActive  bool
	CreatedAt time.Time
}

type Variable struct {
	Key         string
	Value       string
	Description string
	// Encrypted reports that the value is stored sealed with the secret key
	// (#507). It is read-only: writes follow the server's variable_encryption.
	Encrypted bool
	// Unreadable reports a sealed value that no configured secret key opens
	// (the key was rotated without keeping the old one, for example). Value is
	// empty then. Only listings set it; reading the variable alone is an
	// ErrValueUnreadable error.
	Unreadable bool
}

type VariablePatch struct {
	Key         string
	Value       *string
	Description *string
}

type WarmPolicy struct {
	// Enabled is execution.warm_pools_enabled, as the dispatcher sees it (a
	// warm placer is wired).
	Enabled bool
	// ServiceAccount is the operator's default task ServiceAccount, the one a
	// warm worker runs as for its whole life.
	ServiceAccount string
	// Unit is executor.unit (ADR 0066 §3): with it a warm pod is one unit.
	Unit *ResourceUnit
	// Limits is executor.defaults.limits_* (#537): without a unit they size
	// the warm pod.
	Limits *DefaultLimits
	// SourceModeImage is the runtime image when source mode is on, "" when it
	// is off (ADR 0067 §3).
	SourceModeImage string
	// SourceModeWarm is execution.source_mode.warm_pools: a source-mode
	// version may run on warm workers, which receive its dag.py with each
	// assignment (ADR 0095).
	SourceModeWarm bool
}

type WarmPoolDefaults struct {
	// Enabled is execution.warm_pools_enabled: off, no worker is kept warm
	// whatever a DAG declares.
	Enabled bool `json:"enabled"`
	// MinIdleWorkers is execution.min_idle_workers, the idle warm workers
	// kept for a version whose DAG declares none.
	MinIdleWorkers int `json:"min_idle_workers"`
	// MaxPoolSize is execution.max_pool_size, the cap on one version's pool;
	// 0 sets none.
	MaxPoolSize int `json:"max_pool_size"`
}

type WarmVersion struct {
	Image     string
	HasSource bool
	Staging   *StagingConfig
}

type XComEntryMeta struct {
	Key       string
	Timestamp time.Time
	MapIndex  int
}