internal/domain

import "github.com/neochaotic/leoflow/internal/domain"

const DefaultPoolName = "default_pool"

var (
    // ErrCyclicDAG reports a task graph with no valid execution order.
    ErrCyclicDAG = errors.New("cyclic task graph")
    // ErrUnknownDependency reports a depends_on entry naming no declared task.
    ErrUnknownDependency = errors.New("unknown task dependency")
    // ErrDuplicateTaskID reports two tasks declaring the same task_id.
    ErrDuplicateTaskID = errors.New("duplicate task_id")
)

var ErrConflict = errors.New("resource already exists")

var ErrInvalidDbtProject = errors.New("invalid dbt.project")

var ErrInvalidRunID = errors.New("invalid run_id")

var ErrNotFound = errors.New("resource not found")

var ErrUnknownAlertPlaceholder = errors.New("unknown alert placeholder")

var ErrValidation = errors.New("invalid input")

func IsCronlessSchedule(expr string) bool

func IsOnceSchedule(expr string) bool

func ValidateRunID(v string) error

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 Leoflow 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"`
}

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"`
    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
}

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
}

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 a DORMANT seam for per-DAG author-declared warmth: the
    // number of warm workers an author would want kept ready for this DAG version
    // so its tasks skip cold-pod startup (ADR 0058, warm pools model A2). It is NOT
    // author-settable today. There is no author entry point: the field is absent
    // from the authoring schema (leoflow-yaml-schema.json, which is
    // additionalProperties:false) and the parser never emits it, so after the
    // parse→compile path this value is ALWAYS 0. The intended split is that the
    // operator gates IF warmth happens at all (execution.warm_pools_enabled) while
    // the author would only tune HOW MANY, with the operator clamping the request;
    // whether a pod may be reused across attempts stays the operator's security
    // decision. The downstream is intentionally pre-wired around this field —
    // config.ExecutionSection.EffectiveMinIdle already clamps it and the scheduler
    // store already reads it — so exposing it to authors later is a schema+parser
    // change only (add the key to the authoring schema and have the parser emit
    // it), with no domain/scheduler rework. Until then it stays 0 and every DAG,
    // and all of Lite, behaves exactly as before.
    MinIdleWorkers int          `json:"min_idle_workers,omitempty"`
    Catchup        bool         `json:"catchup,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 leoflow.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"`
}

func (d *DAGSpec) CanonicalHash() (string, error)

func (d *DAGSpec) Validate() error

func (d *DAGSpec) ValidateSchedule() error

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
}

type DagRunState string

const (
    // DagRunStateQueued means the run has been created but not started.
    DagRunStateQueued DagRunState = "queued"
    // DagRunStateRunning means at least one task instance is active.
    DagRunStateRunning DagRunState = "running"
    // DagRunStateSuccess means every leaf task reached a successful terminal state.
    DagRunStateSuccess DagRunState = "success"
    // DagRunStateFailed means the run finished with at least one failure.
    DagRunStateFailed DagRunState = "failed"
)

func (s DagRunState) IsTerminal() bool

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: a git describe
    // (tag/SHA) in production, or "dev-<timestamp>" in dev. It is the stable
    // per-deployment identifier under a stable dag_id.
    Version string
}

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, folder, or tag
    // (ADR 0042 §5). Empty means node.
    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 Leoflow 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 DefaultResources struct {
    CPU    string `json:"cpu,omitempty" yaml:"cpu,omitempty"`
    Memory string `json:"memory,omitempty" yaml:"memory,omitempty"`
}

func (d *DefaultResources) AsResources() *Resources

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 Leoflow'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. Leoflow's own leoflow.io/* labels and the task-instance-id annotation win
    // any key collision (the reconciler and terminate path select on them), so a DAG
    // cannot shadow them.
    Labels      map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
    Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty"`
}

type ExecutionMode string

const (
    // ExecutionModePod runs a task inside a worker pod via the agent.
    ExecutionModePod ExecutionMode = "pod"
)

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"`
    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
    // Leoflow deployment concern (not an Airflow DAG attribute), so it lives in
    // leoflow.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
    // `leoflow 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 Leoflow deployment concern (not an
    // Airflow DAG attribute), so it lives in leoflow.yaml and the compiler overlays
    // it onto the produced dag.json.
    Alerts *AlertsConfig `json:"alerts,omitempty" yaml:"alerts,omitempty"`
}

func (c *LeoflowConfig) ApplyDefaults()

func (c *LeoflowConfig) EffectiveDependencies() ([]string, error)

func (c *LeoflowConfig) Validate() error

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 RegistryConfig struct {
    URL         string `json:"url,omitempty" yaml:"url,omitempty"`
    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 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 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 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 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"`
}

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
    // 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 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"`
    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"`
    // 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"`
}

func (t TaskSpec) EffectiveExecutionMode() ExecutionMode

type TaskState string

const (
    // TaskStateNone is the initial state: the task has not been considered yet.
    TaskStateNone TaskState = "none"
    // TaskStateScheduled means dependencies are satisfied and the task is queued for dispatch.
    TaskStateScheduled TaskState = "scheduled"
    // TaskStateQueued means the executor has been asked to start the task.
    TaskStateQueued TaskState = "queued"
    // TaskStateRunning means the task is executing.
    TaskStateRunning TaskState = "running"
    // TaskStateSuccess means the task finished successfully.
    TaskStateSuccess TaskState = "success"
    // TaskStateFailed means the task finished with an error.
    TaskStateFailed TaskState = "failed"
    // TaskStateSkipped means the task was deliberately not run.
    TaskStateSkipped TaskState = "skipped"
    // TaskStateUpstreamFailed means a required upstream failed, so the task cannot run.
    TaskStateUpstreamFailed TaskState = "upstream_failed"
    // TaskStateUpForRetry means the task failed but has retries remaining.
    TaskStateUpForRetry TaskState = "up_for_retry"
    // TaskStateUpForReschedule means a reschedule-mode sensor poked not-ready and
    // released its pod; the scheduler re-dispatches it once reschedule_at is reached,
    // without consuming retry budget (ADR 0040 Phase B, #380). Non-terminal.
    TaskStateUpForReschedule TaskState = "up_for_reschedule"
)

func (s TaskState) IsTerminal() bool

type TaskType string

const (
    // TaskTypePython runs a Python callable identified by an entrypoint.
    TaskTypePython TaskType = "python"
    // TaskTypeBash runs a shell command supplied as the entrypoint.
    TaskTypeBash TaskType = "bash"
    // TaskTypeAirflowOperator runs a captured Airflow provider operator/sensor in
    // the task pod via the generic executor (ADR 0040): the runtime instantiates
    // OperatorClass with OperatorArgs and calls execute(). The provider is
    // installed in the image via connectors:/dependencies:.
    TaskTypeAirflowOperator TaskType = "airflow_operator"
    // TaskTypeDbtGroup is a transient placeholder for a dbt project embedded in a
    // DAG (ADR 0043). The compiler expands it into one task per dbt node and the
    // type never appears in a finished dag.json.
    TaskTypeDbtGroup TaskType = "dbt_group"
)

type TriggerRule string

const (
    // TriggerRuleAllSuccess runs when every upstream succeeded (default).
    TriggerRuleAllSuccess TriggerRule = "all_success"
    // TriggerRuleAllFailed runs when every upstream failed.
    TriggerRuleAllFailed TriggerRule = "all_failed"
    // TriggerRuleAllDone runs once every upstream finished, regardless of state.
    TriggerRuleAllDone TriggerRule = "all_done"
    // TriggerRuleOneSuccess runs as soon as one upstream succeeds.
    TriggerRuleOneSuccess TriggerRule = "one_success"
    // TriggerRuleOneFailed runs as soon as one upstream fails.
    TriggerRuleOneFailed TriggerRule = "one_failed"
)

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

type Variable struct {
    Key         string
    Value       string
    Description string
}

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