execution

type ErroDePasso struct {
	NodeID   string
	ExitCode int
	Mensagem string

	// Saida is the last few lines of stderr. Only the last ones, and not all of
	// them, because a chatty process would fill the database's error column --
	// and the cause is almost always at the end.
	Saida []string
}

type Etapa struct {
	Indice  int            `json:"indice"`
	Nome    string         `json:"nome"`
	Estado  string         `json:"estado"`
	Ms      *int64         `json:"ms,omitempty"`
	Em      string         `json:"em"`
	Numeros map[string]any `json:"numeros,omitempty"`
}

type EtapaGravada = Etapa

type Historico interface {
	PassoJaTeveSucesso(ctx context.Context, workflowSlug, nodeID string, exceto uuid.UUID) (bool, error)
}

type Persistidor interface {
	IniciarTask(ctx context.Context, runID uuid.UUID, nodeID string, tentativa int) error
	TerminarTask(ctx context.Context, runID uuid.UUID, nodeID string, tentativa int,
		status run.Status, exit *int, erro string, log string) error

	// RegistrarEtapas records the phases of an SDK step while it runs. It is
	// what makes the screen advance before the step finishes.
	RegistrarEtapas(ctx context.Context, runID uuid.UUID, nodeID string, tentativa int,
		sdkVersao string, etapas json.RawMessage) error
}

type Reporter interface {
	Evento(execution.Event)
}

type Runner struct {
	Processo execution.Executor // atende `run:`; pode ser nil se so houver tasks Go
	Go       execution.Executor // atende `action:`; pode ser nil

	WorkDir string
	Env     map[string]string
	Report  Reporter

	// Timeout per node. Zero means no limit.
	Timeout time.Duration

	// MaxTentativas per node. Zero or 1 means a single attempt.
	MaxTentativas int
	BackoffBase   time.Duration

	// Persist and RunID are used together: without both, per-step state is not
	// recorded and the DAG in the UI shows up with no execution state.
	Persist Persistidor
	RunID   uuid.UUID

	// Params are this run's values. They reach the step's command through a
	// template (see execution.Renderizar) and the step's environment, so a
	// fetcher using the SDK sees them without being handed an argument.
	Params map[string]string

	// Trigger says why this Run exists: schedule, manual or backfill.
	Trigger string

	// LogicalDate is the slot this Run stands for. Nil on a manual trigger.
	LogicalDate *time.Time

	// Historico decides whether a step is running for the first time. Nil means
	// there is no way to know -- and then the step gets first=false, because
	// creating a table without being sure is worse than not creating it.
	Historico Historico

	// Vagas caps how many STEPS run at once -- in Kubernetes, how many pods
	// exist simultaneously. Nil means no limit.
	//
	// It has to be shared across every Runner in the process, which is why it
	// is injected rather than created here: the ceiling belongs to the CLUSTER,
	// not to one workflow. Without it, the dispatcher's concurrency limit
	// counted RUNS -- five runs with three parallel steps each gave fifteen
	// pods, not five.
	Vagas chan struct{}

	// TentativaDoRun is this RUN's attempt, counted by the dispatcher. It goes
	// into the pod name so a retry does not find the previous attempt's pod.
	TentativaDoRun int

	// Pods runs steps as pods in Kubernetes. When present it serves every step
	// that declares `image:` -- and the same DAG runs as a pod in the cluster
	// and as a process on a laptop, with no change to the YAML.
	Pods execution.Executor
}