engine

type ActivationRef struct {
	// NodeID is the node's ID in the workflow definition (Node.ID).
	NodeID string `json:"node_id"`
	// Seq is the workflow-wide step counter value for this run.
	Seq int64 `json:"seq"`
}

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 CompleteActivation.
	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(WorkflowCompletion) 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)

	// AdminParkHandler is invoked whenever a node parks for admin intervention. See the
	// AdminParkHandler type doc for what a nil handler means.
	AdminParkHandler AdminParkHandler
}

type AdminInterventionResolver interface {
	// ResolveAdminIntervention sends an admin's resolution decision to a node that is
	// currently parked in NodeStatusAwaitingAdmin. workflowID/runID address the execution, and
	// resolution.ActivationID picks the parking within it: it must echo AdminParkPayload.ActivationID
	// (or NodeInfo.ActivationID from GetStatus) for the current park, or the signal is dropped.
	// resolution.NodeID is for display only. A nil return means the signal was delivered, not that
	// it matched a parked node.
	ResolveAdminIntervention(ctx context.Context, workflowID, runID string, resolution AdminResolutionSignal) error
}

type AdminParkHandler func(AdminParkPayload) error

type AdminParkPayload struct {
	// WorkflowID is the unique identifier for the workflow execution that parked.
	WorkflowID string
	// RunID is the unique identifier for this specific execution attempt.
	RunID string
	// CaseID is the case the parked workflow belongs to (see VarCaseID).
	CaseID string
	// NodeID is the ID of the graph node that parked. It names the definition, not this one run of
	// it; see ActivationID for a run.
	NodeID string
	// ActivationID identifies this specific run of the node — the same value NodeInfo.ActivationID
	// held at the moment it parked. A resolution must echo it back (AdminResolutionSignal.ActivationID)
	// to be matched to this parking rather than some other one, including an earlier parking of the
	// same NodeID (a retry or loop revisit mints a new ActivationID each time it parks).
	ActivationID string
	// NodeType is the type of the node that parked (TASK, GATEWAY, etc.).
	NodeType string
	// TaskTemplateID identifies the task template the parked node was running. Empty for
	// non-TASK nodes (e.g. a GATEWAY parked on "no matching conditions").
	TaskTemplateID string
	// Cause is the error message that caused the node to park (NodeInfo.LastError).
	Cause string
	// ParkCategory says why the node parked (see NodeInfo.ParkCategory).
	ParkCategory ParkCategory
	// InputMapping and OutputMapping are the node's mappings from its definition, carried over
	// from NodeInfo.InputMapping/OutputMapping so a handler can report which workflow variable a
	// RETRY reads and which a COMPLETE patch should write, without querying the workflow itself.
	InputMapping  map[string]string
	OutputMapping map[string]string
	// CachedTaskResult holds the Activity's raw result if it had already completed before the
	// node parked (see NodeInfo.CachedTaskResult) — nil if execution never reached that point.
	CachedTaskResult map[string]any
}

type AdminResolutionAction string

type AdminResolutionSignal struct {
	// NodeID is the template node ID (Node.ID) of the parked node, for display/logging. It is not
	// the routing key: ActivationID is.
	NodeID string `json:"nodeID"`
	// ActivationID is the routing key: it must match the ActivationID the engine sent in
	// AdminParkPayload for the parking being resolved. A signal whose ActivationID doesn't match any
	// currently-parked node is dropped — including one echoing an earlier parking of the same
	// NodeID, since a retry or loop revisit mints a new ActivationID each time it parks. Its JSON
	// name, step_id, matches NodeInfo.ActivationID's, so a value read from GetStatus is sent back
	// under the same name.
	ActivationID string `json:"step_id"`
	// Action determines how the node is resolved. See AdminResolutionAction constants.
	Action AdminResolutionAction `json:"action"`
	// WorkflowVariablesPatch sets workflow variables before the action takes effect, for
	// AdminActionRetry and AdminActionComplete. Keys are dotted paths (e.g. "review.outcome"),
	// applied in sorted order, and each value is written the way a task's output mapping writes
	// one: a map value is merged into an existing map at that path (fields it doesn't name are
	// kept), and any other value replaces what is there. It is a patch, not the full variable set
	// — variables not named here are untouched. It is not an RFC 6902 JSON Patch, and a nil value
	// sets the path to nil rather than deleting it. To drop a map's other fields, send it as nil
	// alongside the fields to keep: {"review": nil, "review.outcome": true}. The variables are
	// workflow-wide and persist, so they affect every later node too.
	WorkflowVariablesPatch map[string]any `json:"workflow_variables_patch,omitempty"`
	// Reason is a free-text admin justification, appended to the workflow's AuditTrail.
	Reason string `json:"reason,omitempty"`
}

type BatchGatewayConfig struct {
	// ItemsVariable is the dot-path in WorkflowVariables pointing to the item slice.
	// Defaults to "_items" if empty.
	ItemsVariable string `json:"items_variable,omitempty"`

	// IDField is the field name within each item used as the unique identifier for
	// ID-based merging at the paired BATCH_JOIN. Defaults to "id" if empty.
	IDField string `json:"id_field,omitempty"`
}

type BatchJoinConfig struct {
	// GatewayNodeID is the node ID of the paired BATCH_SPLIT gateway.
	GatewayNodeID string `json:"gateway_node_id"`

	// ItemsVariable is the dot-path in WorkflowVariables pointing to the item slice.
	// Must match the paired BATCH_SPLIT's items_variable. Defaults to "_items" if empty.
	ItemsVariable string `json:"items_variable,omitempty"`

	// IDField is the field name within each item used as the unique identifier.
	// Must match the paired BATCH_SPLIT's id_field. Defaults to "id" if empty.
	IDField string `json:"id_field,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

	// CompleteActivation 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
	// workflowID and activationID (TaskPayload.ActivationID) that were originally emitted via the
	// TaskActivationHandler. runID may be empty to address the workflow's current run. It fails if
	// that step is not pending, so a call for a step that has already completed, or that never
	// existed, is rejected rather than applied to whichever step is active now.
	CompleteActivation(ctx context.Context, workflowID, runID, activationID 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. Returns ErrWorkflowNotFound if there is no queryable
	// current execution for workflowID — see ErrWorkflowNotFound's doc for what that covers.
	GetStatus(ctx context.Context, workflowID string) (*WorkflowInstance, error)
}

type Node struct {
	ID             string            `json:"id"`
	Type           NodeType          `json:"type"`                       // See NodeType constants
	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"`
	Timer        *TimerConfig        `json:"timer,omitempty"`
	Signaling    *SignalingConfig    `json:"signaling,omitempty"`
	BatchGateway *BatchGatewayConfig `json:"batch_gateway,omitempty"`
	BatchJoin    *BatchJoinConfig    `json:"batch_join,omitempty"`
	ParallelJoin *ParallelJoinConfig `json:"parallel_join,omitempty"`
}

type NodeInfo struct {
	// ID is the node's ID in the workflow definition (Node.ID). It names the definition, not one
	// run of it; see ActivationID for a run.
	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

	// ActivationID and Seq identify the most recent run of this node, of any type (see
	// TaskPayload.ActivationID and TaskPayload.Seq, which name the same values for a TASK node
	// specifically). Empty and zero until the node first runs. A node that is revisited gets a new
	// ActivationID and a higher Seq each time; these always describe the latest run.
	ActivationID string `json:"step_id,omitempty"`
	Seq          int64  `json:"seq,omitempty"`

	// 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"`
	// ParkCategory says why the node is parked. Set together with LastError; cleared on resolution.
	ParkCategory ParkCategory `json:"park_category,omitempty"`
	// InputMapping and OutputMapping are the node's mappings from its definition (workflow variable
	// -> task input, task result -> workflow variable), so an admin can see which variables a
	// RETRY reads and which a COMPLETE should write. Set together with LastError, only while the
	// node is parked (not on every node); cleared on resolution.
	InputMapping  map[string]string `json:"input_mapping,omitempty"`
	OutputMapping map[string]string `json:"output_mapping,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 AdminActionComplete over AdminActionRetry to avoid re-running it.
	CachedTaskResult map[string]any `json:"cached_task_result,omitempty"`

	// ChildWorkflowIDs lists the workflow IDs of any child GraphInterpreterWorkflow executions
	// spawned by this node (SPLIT_TASK, BATCH_SPLIT, or PARALLEL_SPLIT). It is set once, at
	// spawn time, and is not derived from the children's current status — so an ID remains
	// listed here even after that child workflow completes. A caller can query each ID with the
	// same GetStatus query used on this workflow to walk the execution tree to arbitrary depth.
	ChildWorkflowIDs []string `json:"child_workflow_ids,omitempty"`
}

type NodeStatus string

type NodeType string

type ParallelJoinConfig struct {
	// GatewayNodeID is the node ID of the paired PARALLEL_SPLIT gateway.
	GatewayNodeID string `json:"gateway_node_id"`

	// MergeByID maps a top-level workflow variable name (holding a []map[string]any shared by
	// multiple branches) to the field name within each item used as its unique ID.
	// Nested dot-paths are not currently supported; see ValidateParallelGateways.
	// TODO: Support nested dot-paths (e.g. "order.items") in MergeByID and mergeVariablesInto.
	MergeByID map[string]string `json:"merge_by_id,omitempty"`
}

type ParkCategory string

type SignalingConfig struct {
	// Type is either EMIT or WAIT.
	Type SignalingType `json:"type"`
	// SignalName is the name of the signal channel. Required.
	SignalName string `json:"signal_name"`
	// Payload holds the data to emit (EMIT nodes only). Ignored for WAIT nodes.
	Payload map[string]any `json:"payload,omitempty"`
}

type SignalingType 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 in the workflow definition (Node.ID). It names the
	// definition, not one run: a node revisited by a loop has the same NodeID each time. Use
	// ActivationID to address one run.
	NodeID string
	// ActivationID identifies this run of the node. It is unique within the workflow, is the ID of the
	// Temporal Activity, and is what Manager.CompleteActivation takes to complete this run. It is derived
	// deterministically from the workflow ID, NodeID and Seq (a UUIDv5), so it is a valid UUID.
	ActivationID string
	// Seq is the workflow-wide step counter value for this run. Every node run (not just TASK)
	// consumes the next value, so a TASK node's Seq need not be contiguous with the previous TASK
	// node's, but it never repeats or goes backwards. Hosts use it to order writes so a late write
	// from an earlier step can be told apart from the current one.
	Seq int64
	// 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
	// CaseID is the case the workflow belongs to (see VarCaseID). It is the same at every level
	// of nesting, so it names the case of a task in a deeply nested child, which WorkflowID
	// alone does not.
	CaseID string
}

type TemporalManager interface {
	Manager

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

	// RegisterAdminParkHandler registers the handler invoked whenever a node parks for admin
	// intervention. Optional — see AdminParkHandler's doc for what a nil/unregistered handler
	// means.
	RegisterAdminParkHandler(handler AdminParkHandler)

	// 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 TimerConfig struct {
	// Duration is how long to wait, as a Go duration string ("30s", "1m", "2h").
	// Required, and must be positive.
	Duration string `json:"duration"`

	// CounterKey is the workflow-variable dot-path the node writes its fire
	// count to, so a downstream gateway can bound a polling loop (for example
	// "status.poll_attempts" against a condition of "< 60"). The count is
	// written before the wait begins and starts at 1. Defaults to
	// "<node id>.iterations".
	CounterKey string `json:"counter_key,omitempty"`
}

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 WorkflowCompletion struct {
	// WorkflowID is the ID of the workflow that completed.
	WorkflowID string
	// Seq is the workflow's step counter taken for the END node's own run, so higher than every
	// other node's Seq in this workflow. A host that orders its writes by Seq uses it to write the
	// completion so a late write from any earlier step matches nothing.
	Seq int64
	// FinalVariables is the workflow's accumulated variables.
	FinalVariables map[string]any
}

type WorkflowCompletionHandler func(WorkflowCompletion) 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"`
}