workflow

type Edge struct {
	From string
	To   string

	// Label is what this dependency MEANS, shown on the arrow.
	//
	//	depends_on:
	//	  - {step: determine_load_type, label: changed existing data}
	//
	// Empty is the normal case and draws nothing. It exists for the branch: a
	// step with two outgoing arrows and no labels is a diagram that requires
	// opening the source to read, which is the one thing a graph is for.
	//
	// Additive in the stored document, like Runtime and Tools: a Workflow is
	// written whole as JSON with no tags, so an older engine ignores the field
	// and this one reading an older document gets "".
	Label string
}

type Kind string

type Node struct {
	ID     string
	Run    string
	Action string
	With   map[string]any

	// Image overrides the workflow's. Empty inherits.
	Image string

	// Resources sizes this step's pod. The gain from separating per step is
	// concrete: a Go fetcher fits in 64Mi while the dbt next to it asks for
	// 1Gi, and under a single image both would pay the larger of the two.
	Resources Resources

	// Runtime and Tools say what this step runs in. Both empty is the normal
	// case: the engine infers from Run and Image, and only what the author
	// DECLARED lands here.
	//
	// They are additive in the stored document. A Workflow is written whole as
	// JSON into workflows.definicao and runs.definicao with no tags, so the Go
	// field name is the key -- an older engine ignores what it does not know,
	// and this one reading an older document gets the zero value, which means
	// "not declared" and falls through to the inference. Nothing to migrate.
	// See TestTheParamKeysAreTheOnDiskFormat for the case where that is NOT
	// true.
	Runtime string
	Tools   []string

	// UnlessEmpty names a context key that decides whether this step runs.
	//
	//	- id: transform
	//	  depends_on: [extract]
	//	  unless_empty: extract.has_rows
	//
	// A KEY, not an expression. The tempting design is
	// `when: "{{ context.extract.rows > 0 }}"`, and a mini expression language
	// is a large commitment: a parser, a type system to say what `>` means
	// across a JSON `any`, a security story because the expression comes out of
	// a YAML somebody else wrote, and error messages that point into a string.
	// Every orchestrator that has one has a bug tracker full of it.
	//
	// Here the STEP decides and publishes a boolean, so the decision lives in
	// the language its author already writes and is testable with their own
	// test framework. The engine reads one key and asks whether it is empty.
	UnlessEmpty string

	// Uses names another workflow whose steps take this one's place.
	//
	//	- id: mlops
	//	  uses: ml_training
	//	  depends_on: [prepare]
	//
	// Expanded at PUBLISH, not at run time: the child's steps become part of
	// this graph, prefixed with this step's id, and this node disappears.
	//
	// The alternative -- a step that triggers a child RUN and waits -- is the
	// design that deadlocked Airflow, and this engine has the same ingredient:
	// Runner.Slots is a per-process semaphore, so a parent holding a slot while
	// waiting for a child that needs slots from the same pool hangs. It appears
	// only under load, which is to say in production.
	//
	// Expansion gives up a child run with its own id and its own history. One
	// run, one graph, one pool.
	Uses string

	// Group draws this step inside a named, collapsible box on the graph.
	//
	//	- id: extract_orders
	//	  group: sales_data_reporting
	//
	// VISUAL only, and that is a decision rather than a shortcut. Airflow's
	// TaskGroups also PREFIX the ids inside them, so `extract` in a group
	// becomes `sales.extract` -- which would change every `depends_on`, every
	// context key and every task_runs row in an existing workflow, for a
	// feature whose whole value is that a big graph is readable. Namespacing
	// can be added later; it is a strict addition to this.
	//
	// A group is a LABEL, not a container: steps keep their global ids, a group
	// may span levels, and nothing about execution changes.
	Group string

	// ForEach maps this step over a list published by a step above it.
	//
	//	- id: load
	//	  depends_on: [extract]
	//	  for_each: extract.partitions
	//
	// The step runs once per element, each with a row, a retry and an exit code
	// of its own. The DAG's SHAPE does not change -- it is still one node with
	// one set of edges, and only the number of rows under it varies -- which is
	// what makes this cheap: graph.Levels never sees it.
	//
	// The fan-out is bounded for free. The list travels in the context, and the
	// context has a 4096-byte ceiling inherited from the kubelet, so a workflow
	// cannot ask for ten thousand pods without first finding a way to say so in
	// four kilobytes. That is a limit worth keeping rather than working around.
	ForEach string

	// Marker says this step does nothing and exists to be a point in the graph.
	//
	//	- id: start
	//	  marker: true
	//
	// It is the EmptyOperator every orchestrator ends up with, and it is not
	// decoration: an `end` that depends on everything turns "did the whole
	// thing finish?" into one node instead of six arrows to follow. Without it,
	// Validate refuses a step with neither `run` nor `action` -- correctly,
	// because that is almost always a mistake, and the two cases must not
	// collapse into one.
	Marker bool

	// When is the trigger rule: under what state of its dependencies this step
	// runs at all. Empty is WhenAllSuccess, which is what every workflow
	// published before this existed means.
	//
	//	- id: notify_failure
	//	  depends_on: [extract]
	//	  when: any_failed
	When string

	// OnError declares that this step announces its own failures.
	//
	//	on_error:
	//	  type: SLACK
	//
	// The DESTINATION is not here and never will be. A webhook is a credential
	// -- whoever holds it posts in the channel as if they were the platform --
	// and a workflow file is written by somebody who is not necessarily allowed
	// to choose where the company's alerts go. The YAML says WHETHER and HOW;
	// the installation says WHERE, through the same environment variable it
	// already uses. It is the argument that made BREVIS_POD_ALLOWED_SECRETS a
	// list the installation controls rather than something the YAML picks.
	//
	// Absent is the normal case: the run-level alert already fires when a run
	// gives up, with no block repeated in any file.
	OnError *OnError

	// Shell decides how the command enters the container. Nil means with a
	// shell, which is what `run:` suggests ("python fetch.py"). False passes the
	// argv directly, for a distroless image -- where `sh -c` would fail with
	// "no such file or directory", an error that says nothing about the
	// cause.
	Shell *bool

	// Env are this step's environment variables, with a literal value in the
	// file. They override the workflow's, name by name.
	//
	//	env:
	//	  BREVIS_LOG_LEVEL: info
	Env map[string]string

	// Secrets are variables whose VALUE never appears in the file. The key is
	// the variable's name; the value is where to find it, as `secret/key`.
	//
	//	secrets:
	//	  GABRIEL_SESSION_COOKIE: gabriel-session/cookie
	//
	// Two keys and not one, on purpose. With a single one, the shortest path to
	// making it work would be pasting the secret into the YAML -- and the YAML
	// is in git. `env:` accepts a literal, `secrets:` does not.
	//
	// Where the coordinate resolves depends on the executor, and the asymmetry
	// is deliberate:
	//
	//   Kubernetes  valueFrom.secretKeyRef{name: gabriel-session, key: cookie}
	//   local       the variable of the same name in the engine's own
	//               environment, and missing is an ERROR -- not an empty string
	//
	// In either case the engine passes it on without reading: the value enters
	// no log, no database and no rendered command.
	Secrets map[string]string
}

type OnError struct {
	// Type is the channel. Required: an on_error with no type is a step that
	// asks to be announced somewhere unspecified.
	Type string

	// When is OnGiveUp (default) or OnAttempt.
	When string
}

type Param struct {
	Name        string    `json:"Nome"`
	Type        ParamType `json:"Tipo"`
	Default     string    `json:"Default"`
	Description string    `json:"Descricao"`

	// Enum restricts the accepted values. Empty = any that passes the type.
	Enum []string `json:"Enum"`

	// Pattern is a regular expression the value has to match. It exists for the
	// author to WIDEN what the `string` type accepts by default — see
	// safeCharacters.
	Pattern string `json:"Pattern"`
}

type ParamType string

type Resources struct {
	CPU         string
	Memory      string
	CPULimit    string
	MemoryLimit string
}

type Workflow struct {
	Slug     string
	Name     string
	Kind     Kind
	Schedule string // cron; vazio = so disparo manual

	// Tags classify the workflow for search and filtering in the UI. They are
	// free-form labels from the YAML's author, not domain: nothing in the
	// engine depends on them.
	Tags []string

	// Image is the steps' default runtime. In Kubernetes EVERY step becomes a
	// pod, and the image is what defines what that pod knows how to do: a dbt
	// step brings up the dbt image, a Go binary brings up a 10 MB one.
	// Declaring it here avoids repeating the same line in ten steps; a step
	// overrides it when it needs a different runtime.
	Image string

	// Resources is the default CPU and memory request, for the same reason.
	Resources Resources

	// Env are environment variables every step receives. A literal value, which
	// is why they are NOT for secrets: the YAML is in git.
	Env map[string]string

	// Secrets are variables whose value the engine neither sees nor stores. See Node.
	Secrets map[string]string

	// Params are the values that change between two dispatches of the same
	// workflow -- `load_full`, a date window, a limit. See param.go.
	Params []Param

	// MaxActive caps simultaneous runs OF THIS workflow. Zero means no limit.
	//
	// It differs from the global step ceiling: that one protects the CLUSTER,
	// this one protects the DATA. A `*/15` that takes 20 minutes overlaps
	// itself, and two `dbt build` on the same model at once fight over the same
	// table.
	MaxActive int

	Nodes []Node
	Edges []Edge
}