workflow

type Edge struct {
	From string
	To   string
}

type Kind string

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

	// Image sobrescreve a do workflow. Vazio = herda.
	Image string

	// Resources dimensiona o pod deste passo. O ganho de separar por passo e
	// concreto: um fetcher em Go cabe em 64Mi enquanto o dbt ao lado pede 1Gi, e
	// numa imagem unica os dois pagariam o maior dos dois.
	Resources Resources

	// Shell decide como o comando entra no container. Nulo = com shell, que e o
	// que `run:` sugere ("python fetch.py"). Falso passa o argv direto, para
	// imagem distroless — onde `sh -c` falharia com "no such file or directory",
	// erro que nao diz nada sobre a causa.
	Shell *bool

	// Env sao variaveis de ambiente deste passo, com valor literal no arquivo.
	// Sobrescrevem as do workflow, nome a nome.
	//
	//	env:
	//	  BREVIS_LOG_LEVEL: info
	Env map[string]string

	// Secrets sao variaveis cujo VALOR nunca aparece no arquivo. A chave e o
	// nome da variavel; o valor e onde encontra-la, no formato `secret/chave`.
	//
	//	secrets:
	//	  GABRIEL_SESSION_COOKIE: gabriel-session/cookie
	//
	// Sao duas chaves e nao uma de proposito. Com uma so, o caminho mais curto
	// para fazer funcionar seria colar o segredo no YAML — e o YAML esta no
	// git. `env:` aceita literal, `secrets:` nao aceita.
	//
	// Onde a coordenada resolve depende do executor, e a assimetria e
	// deliberada:
	//
	//   Kubernetes  valueFrom.secretKeyRef{name: gabriel-session, key: cookie}
	//   local       a variavel de mesmo nome no ambiente do proprio motor,
	//               e ausente e ERRO — nao string vazia
	//
	// Em qualquer um dos dois o motor repassa sem ler: o valor nao entra em
	// log, nem no banco, nem no comando renderizado.
	Secrets map[string]string
}

type Param struct {
	Nome      string
	Tipo      TipoParam
	Padrao    string
	Descricao string

	// Enum restringe os valores aceitos. Vazio = qualquer um que passe no tipo.
	Enum []string

	// Pattern e uma expressao regular que o valor precisa casar. Existe para o
	// autor AMPLIAR o que o tipo `string` aceita por padrao — ver `seguro`.
	Pattern string
}

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

type TipoParam string

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

	// Tags classificam o workflow para busca e filtro na UI. Sao rotulos livres
	// do autor do YAML, nao dominio: nada no motor depende delas.
	Tags []string

	// Image e o runtime padrao dos passos. Em Kubernetes CADA passo vira um pod,
	// e a imagem e o que define o que aquele pod sabe fazer: um passo de dbt
	// sobe a imagem de dbt, um binario Go sobe uma imagem de 10 MB. Declarar
	// aqui evita repetir a mesma linha em dez passos; o passo sobrescreve quando
	// precisa de outro runtime.
	Image string

	// Resources e o pedido padrao de CPU e memoria, pela mesma razao.
	Resources Resources

	// Env sao variaveis de ambiente que todo passo recebe. Valor literal, e
	// por isso NAO servem para segredo: o YAML esta no git.
	Env map[string]string

	// Secrets sao variaveis cujo valor o motor nao ve nem guarda. Ver Node.
	Secrets map[string]string

	// Params sao os valores que mudam entre dois disparos do mesmo workflow —
	// `load_full`, uma janela de datas, um limite. Ver param.go.
	Params []Param

	// MaxAtivos limita execucoes simultaneas DESTE workflow. Zero = sem limite.
	//
	// E diferente do teto global de passos: aquele protege o CLUSTER, este
	// protege o DADO. Um `*/15` que leva 20 minutos se sobrepoe a si mesmo, e
	// dois `dbt build` no mesmo modelo ao mesmo tempo disputam a mesma tabela.
	MaxAtivos int

	Nodes []Node
	Edges []Edge
}