workflow

type Definition struct {
	DocType      string
	States       []State
	Transitions  []Transition
	OnTransition map[string]Handler // keyed by destination State.Name
}

type Engine interface {
	Register(def Definition) error
	AvailableTransitions(ctx context.Context, docType, currentState string) []Transition
	Execute(ctx context.Context, docType, id, action string) error
	// DocTypes lists every DocType with a registered workflow definition.
	// Consumed by the agent ToolRegistry at compile time to emit exactly one
	// execute_action_{doctype} tool per workflowed DocType (TAD §10.1 step 6).
	DocTypes() []string
}

type GuardFunc func(ctx context.Context, doc map[string]any) error

type Handler func(ctx context.Context, doc map[string]any) error

type State struct {
	Name  string
	Style string // UI hint only: "gray" | "yellow" | "green" | "red" | a hex color
}

type Transition struct {
	From         string
	To           string
	Action       string // verb surfaced as a UI button label and an agent enum value
	AllowedRoles []string
	Guard        GuardFunc // optional; evaluated after the AllowedRoles check
}