omniworkflow

type Plan struct {
	Steps []PlanStep `json:"steps"`
}

type PlanStep struct {
	// ID uniquely identifies the step within its Plan.
	ID string `json:"id"`
	// DependsOn lists step IDs that must succeed before this step is ready.
	// Empty means the step is ready immediately.
	DependsOn []string `json:"dependsOn,omitempty"`
	// Gate, when true, makes the step hold once ready until an approval
	// Signal (ApproveSignal(ID)) is delivered, then execute.
	Gate bool `json:"gate,omitempty"`
	// Input is opaque data passed to the StepExecutor verbatim.
	// JSON-serializable; after crossing the provider boundary it is decoded
	// as generic JSON (e.g. map[string]any), so executors should treat it as
	// such rather than relying on a concrete Go type identity.
	Input any `json:"input,omitempty"`
}

type Run struct {
	ID       string
	Status   RunStatus
	Output   any               // populated on success; JSON-serializable
	Metadata map[string]string // provider-specific extras, opt-in (e.g. execution ARN)
}

type RunStatus string

type Signal struct {
	Name    string
	Payload any // JSON-serializable
}

type StartRequest struct {
	// ID is the caller-assigned run identity and idempotency key.
	ID string
	// Plan is the DAG to execute.
	Plan Plan
}

type StepExecutor interface {
	ExecuteStep(ctx context.Context, runID string, step PlanStep) (output any, err error)
}

type Worker interface {
	// Run starts the worker and blocks until ctx is cancelled or a fatal
	// error occurs. A clean shutdown via ctx cancellation returns nil.
	Run(ctx context.Context) error
}

type WorkflowProvider interface {
	// Start begins executing req.Plan. The run is identified by req.ID, which
	// is also the idempotency key: starting again with the same ID must not
	// create a duplicate execution (it returns the existing run).
	Start(ctx context.Context, req StartRequest) (*Run, error)

	// Get returns the current state of the run with the given id.
	// It returns ErrRunNotFound if no such run exists.
	Get(ctx context.Context, id string) (*Run, error)

	// Signal delivers a signal to a running run — most importantly the
	// approval of a Gate step (see ApproveSignal). It returns ErrRunNotFound
	// if no such run exists.
	Signal(ctx context.Context, id string, signal Signal) error

	// Cancel requests cancellation of the run. After cancellation no further
	// steps execute and the run's terminal status is StatusCancelled.
	Cancel(ctx context.Context, id string) error
}