engine

type Activities struct {
	// ExecuteTaskActivityHandler is invoked when the workflow engine encounters a task node.
	// - For synchronous execution, it should return a nil error with a map containing the results.
	// - For asynchronous execution, it should return a nil map and an ErrResultPending error,
	//   which pauses the workflow activity until an external handler triggers TaskDone.
	ExecuteTaskActivityHandler func(TaskPayload) (map[string]any, error)

	// WorkflowCompletedActivityHandler is invoked when the overall workflow execution succeeds and reaches
	// an End node. It receives the workflow ID and the final accumulated workflow variables, allowing the
	// host application to run any necessary completion triggers, notify listeners, or persist final state.
	WorkflowCompletedActivityHandler func(string, map[string]any) error

	// FetchWorkflowDefinitionHandler is invoked to dynamically retrieve the workflow definition structure
	// for a given template ID during SPLIT_TASK execution.
	FetchWorkflowDefinitionHandler func(templateID string) (WorkflowDefinition, error)
}

type AdminInterventionResolver interface {
	// ResolveAdminIntervention sends an admin's resolution decision to a node that is
	// currently parked in NodeStatusAwaitingAdmin, identified by workflowID/runID/nodeID.
	ResolveAdminIntervention(ctx context.Context, workflowID, runID string, resolution AdminResolutionSignal) error
}

type AdminResolutionAction string

type AdminResolutionSignal struct {
	// NodeID is the template node ID (Node.ID) of the parked node — the routing key.
	NodeID string `json:"nodeID"`
	// Action determines how the node is resolved. See AdminResolutionAction constants.
	Action AdminResolutionAction `json:"action"`
	// Overrides are merged into WorkflowVariables for AdminActionOverride/AdminActionSkip,
	// or merged in before retrying for AdminActionRetry.
	Overrides map[string]any `json:"overrides,omitempty"`
	// Reason is a free-text admin justification, appended to the workflow's AuditTrail.
	Reason string `json:"reason,omitempty"`
}

type BroadcastMessage struct {
	SenderBranchID string         `json:"sender_branch_id"`
	SignalName     string         `json:"signal_name"`
	Payload        map[string]any `json:"payload"`
}

type Edge struct {
	ID        string `json:"id"`
	SourceID  string `json:"source_id"`
	TargetID  string `json:"target_id"`
	Condition string `json:"condition,omitempty"` // Expression mapped against WorkflowVariables
}

type ExecutionStatus string

type FailureMode string

type GatewayType string

type Manager interface {
	// StartWorkflow starts a workflow using the provided ID.
	// The WorkflowDefinition defines the structure of the workflow graph (nodes and edges).
	// initialWorkflowVariables sets the starting state for the graph's
	// data payload. Returns an error if submission fails.
	StartWorkflow(ctx context.Context, ID string, def WorkflowDefinition, initialWorkflowVariables map[string]any) error

	// TaskDone is called by the external system to resume a paused workflow node.
	// It routes the output data back into the specific workflow's WorkflowVariables using the provided
	// IDs (workflowID, runID, nodeID) that were originally emitted via the TaskActivationHandler.
	TaskDone(ctx context.Context, workflowID, runID, nodeID string, output map[string]any) error

	// TaskUpdate is used to send an update about the task to the workflow.
	// This is typically used to append messages to the workflow's internal state or update
	// UI with hints, progress updates, or audit trail messages.
	// It does not advance the graph's execution state.
	TaskUpdate(ctx context.Context, workflowID, runID string, update UpdateEvent) error

	// GetStatus retrieves a running workflow's in-memory state (the WorkflowInstance), including
	// current variables, and audit trails.
	GetStatus(ctx context.Context, workflowID string) (*WorkflowInstance, error)
}

type Node struct {
	ID             string            `json:"id"`
	Type           NodeType          `json:"type"`                       // START, END, TASK, GATEWAY, or SPLIT_TASK
	GatewayType    GatewayType       `json:"gateway_type,omitempty"`     // See Gateway Types constants
	TaskTemplateID string            `json:"task_template_id,omitempty"` // Identifier for the task template to run
	InputMapping   map[string]string `json:"input_mapping,omitempty"`    // Maps WorkflowVariables Key -> Task Input Key
	OutputMapping  map[string]string `json:"output_mapping,omitempty"`   // Maps Task Output Key -> WorkflowVariables Key

	// Extensions
	SplitTask *SplitTaskConfig `json:"split_task,omitempty"`
}

type NodeInfo struct {
	ID             string      `json:"id"`
	CreatedAt      time.Time   `json:"createdAt"`                  // Timestamp of node creation
	UpdatedAt      time.Time   `json:"updatedAt"`                  // Timestamp of last node update
	Type           NodeType    `json:"type"`                       // Type of the node.
	GatewayType    GatewayType `json:"gateway_type,omitempty"`     // See Gateway Types constants
	TaskTemplateID string      `json:"task_template_id,omitempty"` // Identifier for the task template to run
	Status         NodeStatus  `json:"status"`                     // Status of the node

	// LastError holds the error that caused the node to enter NodeStatusAwaitingAdmin
	// (or the terminal error if it was ultimately aborted). Cleared on successful resolution.
	LastError string `json:"last_error,omitempty"`
	// CachedTaskResult holds the most recent raw Activity result for a TASK node, set right
	// after the Activity succeeds and cleared once the node fully completes. It is purely
	// informational: if a node parks with this populated, the Activity has already run, so
	// an admin should prefer AdminActionOverride over AdminActionRetry to avoid re-running it.
	CachedTaskResult map[string]any `json:"cached_task_result,omitempty"`
}

type NodeStatus string

type NodeType string

type SplitMode string

type SplitTaskConfig struct {
	Mode            SplitMode   `json:"mode"`                       // SAME_TEMPLATE or DIFFERENT_TEMPLATES
	ItemsVariable   string      `json:"items_variable"`             // Global context variable dot-path pointing to []map[string]any
	ResultsVariable string      `json:"results_variable,omitempty"` // Destination path to save aggregated sub-workflow outputs
	FailureMode     FailureMode `json:"failure_mode"`               // FAIL_FAST or COLLECT_ALL
	IterationKey    string      `json:"iteration_key,omitempty"`    // Override key for sub-context namespace. Defaults to "_iter"
}

type SplitTaskItem struct {
	TemplateID string         `json:"template_id"`
	BranchID   string         `json:"branch_id"`
	Payload    map[string]any `json:"payload"`
}

type TaskActivationHandler func(payload TaskPayload) (map[string]any, error)

type TaskPayload struct {
	// WorkflowID is the unique identifier for the overall business process instance.
	WorkflowID string
	// RunID is the unique identifier for this specific execution attempt.
	RunID string
	// NodeID is the ID of the graph node currently being executed. This should be
	// unique for each node in the workflow.
	NodeID string
	// TaskTemplateID identifies the specific type of external work/script the task executor should run.
	TaskTemplateID string
	// Inputs contains the specific subset of WorkflowVariables mapped to this task's requirements.
	Inputs map[string]any
}

type TemporalManager interface {
	Manager

	// RegisterDefinitionHandler registers the handler function for fetching sub-workflow definitions.
	RegisterDefinitionHandler(handler func(templateID string) (WorkflowDefinition, error))

	// StartWorker connects the internal Temporal Worker to the Temporal Server and
	// begins polling the task queue for workflow and activity tasks.
	StartWorker() error

	// StopWorker gracefully shuts down the internal Temporal Worker, stopping it from
	// pulling new tasks while allowing currently executing tasks to finish.
	StopWorker()
}

type UpdateEvent struct {
	// EventType categorizes the signal (e.g., "AUDIT", "PROGRESS_UPDATE", "UI_HINT")
	// so the workflow knows how to route the data internally.
	EventType string `json:"eventType"`
	// NodeID is the ID of the graph node being updated.
	NodeID string `json:"nodeID"`
	// Payload contains the contextual data for the event (e.g., percentage complete, or audit text).
	Payload map[string]any `json:"payload,omitempty"`
}

type WorkflowCompletionHandler func(workflowID string, finalWorkflowVariables map[string]any) error

type WorkflowDefinition struct {
	// ID is the unique identifier for this specific workflow template.
	ID string `json:"id"`

	// Name is a human-readable label used for display and organizational purposes.
	Name string `json:"name"`

	// Version tracks iterations of the workflow logic, allowing for side-by-side
	// deployment of different logic versions.
	Version int `json:"version"`

	// Nodes defines the individual steps, gateways, and boundary events
	// that make up the workflow.
	Nodes []Node `json:"nodes"`

	// Edges defines the directed connections between nodes, including
	// any conditional logic required for branching.
	Edges []Edge `json:"edges"`
}

type WorkflowInstance struct {
	// ID is the unique ID for this instance of the workflow.
	ID string `json:"id"`
	// Status represents the current execution state.
	Status ExecutionStatus `json:"status"`
	// WorkflowVariables holds the shared, dynamic business data passed between nodes.
	WorkflowVariables map[string]any `json:"workflow_variables"`
	// AuditTrail is a chronologically ordered log of events, milestones, or external signals.
	AuditTrail []string             `json:"audit_trail"`
	NodeInfo   map[string]*NodeInfo `json:"node_states"`
	// Edges contains the workflow graph connections from the workflow definition.
	Edges []Edge `json:"edges"`
}