workflow

type Activity interface {

	// Name returns the name of the Activity
	Name() string

	// Execute the Activity with the given parameters.
	Execute(ctx Context, parameters map[string]any) (any, error)
}

type ActivityExecutionEvent struct {
	ExecutionID  string
	WorkflowName string
	BranchID     string
	StepName     string
	ActivityName string
	Parameters   map[string]any
	Result       any
	StartTime    time.Time
	EndTime      time.Time
	Duration     time.Duration
	Error        error
}

type ActivityLogEntry struct {
	ID          string                 `json:"id"`
	ExecutionID string                 `json:"execution_id"`
	Activity    string                 `json:"activity"`
	StepName    string                 `json:"step_name"`
	BranchID    string                 `json:"branch_id"`
	Parameters  map[string]interface{} `json:"parameters"`
	Result      interface{}            `json:"result,omitempty"`
	Error       string                 `json:"error,omitempty"`
	StartTime   time.Time              `json:"start_time"`
	Duration    float64                `json:"duration"`
}

type ActivityLogger interface {
	// LogActivity logs a completed activity
	LogActivity(ctx context.Context, entry *ActivityLogEntry) error

	// GetActivityHistory retrieves activity log for an execution
	GetActivityHistory(ctx context.Context, executionID string) ([]*ActivityLogEntry, error)
}

type ActivityRegistry struct {
	// contains filtered or unexported fields
}

type AtomicCheckpointer interface {
	// AtomicUpdate loads the checkpoint for the given execution,
	// runs fn against the loaded copy, and saves the result. The
	// entire read-modify-write cycle must be atomic with respect to
	// other writers of the same execution.
	//
	// If fn returns an error the checkpoint MUST NOT be saved; the
	// error is returned verbatim to the caller.
	//
	// If no checkpoint exists for the execution ID, AtomicUpdate
	// returns ErrNoCheckpoint without invoking fn.
	AtomicUpdate(ctx context.Context, executionID string, fn func(*Checkpoint) error) error
}

type BaseExecutionCallbacks struct{}

type BranchExecutionEvent struct {
	ExecutionID  string
	WorkflowName string
	BranchID     string
	Status       ExecutionStatus
	StartTime    time.Time
	EndTime      time.Time
	Duration     time.Duration
	CurrentStep  string
	StepOutputs  map[string]any
	Error        error
}

type BranchLocalState struct {
	// contains filtered or unexported fields
}

type BranchState struct {
	ID           string          `json:"id"`
	Status       ExecutionStatus `json:"status"`
	CurrentStep  string          `json:"current_step"`
	StartTime    time.Time       `json:"start_time,omitzero"`
	EndTime      time.Time       `json:"end_time,omitzero"`
	ErrorMessage string          `json:"error_message,omitempty"`
	StepOutputs  map[string]any  `json:"step_outputs"`
	Variables    map[string]any  `json:"variables"`
	// Wait is populated when the branch is hard-suspended on a durable
	// wait (signal-wait or durable sleep). nil otherwise.
	Wait *WaitState `json:"wait,omitempty"`
	// PauseRequested marks a branch as paused by an explicit pause
	// trigger — either an external PauseBranch call or a declarative
	// Pause step. A branch with PauseRequested=true will re-park at its
	// next step boundary after construction; UnpauseBranch must clear
	// the flag before the branch can advance.
	PauseRequested bool `json:"pause_requested,omitempty"`
	// PauseReason is an optional human-readable note describing why
	// the branch was paused. Set by the PauseBranch caller or by a
	// PauseConfig.Reason on a declarative Pause step.
	PauseReason string `json:"pause_reason,omitempty"`
	// ActivityHistory is the persisted cache for the currently
	// executing activity. It survives wait-unwind replays so
	// activities can cache expensive work across suspensions via
	// [Context.History] + [History.RecordOrReplay]. Cleared
	// when the step advances past the activity so there is no
	// cross-step leakage.
	ActivityHistory map[string]any `json:"activity_history,omitempty"`
	// ActivityHistoryStep records which step's activity owns the
	// current ActivityHistory map. executeActivity uses it to scope
	// history access to a single step: if the branch has raced ahead to
	// a new step before the orchestrator cleared the prior step's
	// history, the mismatch discards the stale entries so they do not
	// leak into the next activity.
	ActivityHistoryStep string `json:"activity_history_step,omitempty"`
}

type CallbackChain struct {
	// contains filtered or unexported fields
}

type CatchConfig struct {
	ErrorEquals []string `json:"error_equals"`
	Next        string   `json:"next"`
	Store       string   `json:"store,omitempty"`
}

type Checkpoint struct {
	// SchemaVersion is the wire-format version. Set to
	// CheckpointSchemaVersion by the engine on every save.
	SchemaVersion int `json:"schema_version"`

	// ID is the unique identifier for this checkpoint snapshot.
	// Distinct from ExecutionID: a single execution writes many
	// checkpoints over its lifetime.
	ID string `json:"id"`

	// ExecutionID is the ID of the execution this checkpoint belongs
	// to. Stable across all snapshots of the same execution.
	ExecutionID string `json:"execution_id"`

	// WorkflowName is the name of the workflow definition used to
	// produce the execution. Informational — the engine does not
	// consult it on resume.
	WorkflowName string `json:"workflow_name"`

	// Status is the execution status at the time the checkpoint was
	// written.
	Status ExecutionStatus `json:"status"`

	// Inputs is the workflow's input values, as supplied on
	// NewExecution. Immutable for the lifetime of the execution.
	Inputs map[string]any `json:"inputs"`

	// Outputs is the declared workflow outputs extracted from the
	// final branch states when the execution completes. Empty until
	// then.
	Outputs map[string]any `json:"outputs"`

	// Variables is the top-level workflow state, distinct from
	// per-branch state. Used by the orchestrator for shared values
	// that are not branch-local.
	Variables map[string]any `json:"variables"`

	// BranchStates holds the per-branch persisted state, keyed by
	// branch ID. Each entry captures the branch's variables, current
	// step, retry counters, and any active WaitState.
	BranchStates map[string]*BranchState `json:"branch_states"`

	// JoinStates holds the persisted state for active join steps,
	// keyed by join step name.
	JoinStates map[string]*JoinState `json:"join_states"`

	// BranchCounter is the monotonic counter used to allocate
	// branch IDs. Persisted so resumed executions continue to
	// allocate unique IDs.
	BranchCounter int `json:"branch_counter"`

	// Error is the terminal error message when Status is
	// ExecutionStatusFailed. Empty otherwise.
	Error string `json:"error,omitempty"`

	// StartTime is when the execution first began running.
	StartTime time.Time `json:"start_time,omitzero"`

	// EndTime is when the execution reached a terminal status
	// (completed, failed, or canceled). Zero for in-flight or
	// suspended executions.
	EndTime time.Time `json:"end_time,omitzero"`

	// CheckpointAt is when this snapshot was written.
	CheckpointAt time.Time `json:"checkpoint_at"`
}

type Checkpointer interface {
	// SaveCheckpoint persists the given checkpoint snapshot. The
	// engine sets SchemaVersion = CheckpointSchemaVersion on every
	// call; implementations should record it verbatim.
	SaveCheckpoint(ctx context.Context, checkpoint *Checkpoint) error

	// LoadCheckpoint returns the most recent checkpoint for the
	// given execution ID. Returns ErrNoCheckpoint when no
	// checkpoint exists for the execution. Implementations MUST
	// reject any loaded checkpoint whose SchemaVersion is greater
	// than CheckpointSchemaVersion — the library did not write it
	// and cannot safely interpret it.
	LoadCheckpoint(ctx context.Context, executionID string) (*Checkpoint, error)

	// DeleteCheckpoint removes checkpoint data for an execution.
	DeleteCheckpoint(ctx context.Context, executionID string) error
}

type ChildWorkflowExecutor interface {
	// ExecuteSync runs a child workflow synchronously and waits for completion
	ExecuteSync(ctx context.Context, spec *ChildWorkflowSpec) (*ChildWorkflowResult, error)

	// ExecuteAsync starts a child workflow asynchronously and returns immediately
	ExecuteAsync(ctx context.Context, spec *ChildWorkflowSpec) (*ChildWorkflowHandle, error)

	// GetResult retrieves the result of an asynchronous execution
	GetResult(ctx context.Context, handle *ChildWorkflowHandle) (*ChildWorkflowResult, error)
}

type ChildWorkflowExecutorOptions struct {
	WorkflowRegistry WorkflowRegistry
	Activities       []Activity
	Logger           *slog.Logger
	ActivityLogger   ActivityLogger
	Checkpointer     Checkpointer
	// ScriptCompiler is the scripting engine used by child executions.
	// When nil, child executions fall back to DefaultScriptCompiler
	// (github.com/deepnoodle-ai/expr). Set this to override with a
	// different engine.
	ScriptCompiler script.Compiler
	// CleanupTimeout is how long to retain an async child workflow's
	// result in memory after completion before evicting it from the
	// in-flight map. GetResult on an evicted handle returns an error.
	// Zero (the default) means one hour. Negative values disable
	// cleanup entirely (results are retained for the lifetime of the
	// process — useful in tests, dangerous in long-running services).
	CleanupTimeout time.Duration
}

type ChildWorkflowHandle struct {
	ExecutionID  string `json:"execution_id"`
	WorkflowName string `json:"workflow_name"`
}

type ChildWorkflowResult struct {
	Outputs     map[string]interface{} `json:"outputs"`
	Status      ExecutionStatus        `json:"status"`
	ExecutionID string                 `json:"execution_id"`
	Duration    time.Duration          `json:"duration"`
}

type ChildWorkflowSpec struct {
	WorkflowName string                 `json:"workflow_name"`
	Inputs       map[string]interface{} `json:"inputs,omitempty"`
	Timeout      time.Duration          `json:"timeout,omitempty"`
	ParentID     string                 `json:"parent_id,omitempty"` // for tracing
}

type CompletionHook func(ctx context.Context, result *ExecutionResult) ([]FollowUpSpec, error)

type Context interface {
	context.Context

	// Inputs returns a read-only view over the workflow inputs for
	// this branch.
	Inputs() Inputs

	// Set writes a branch-local variable.
	Set(key string, value any)
	// Get returns a branch-local variable and whether it was present.
	Get(key string) (value any, exists bool)
	// Delete removes a branch-local variable.
	Delete(key string)
	// Keys returns the names of all branch-local variables in sorted
	// order.
	Keys() []string

	// Logger returns the slog.Logger configured on the execution,
	// scoped to this execution and branch.
	Logger() *slog.Logger
	// Compiler returns the script.Compiler configured on the
	// execution.
	Compiler() script.Compiler
	// BranchID returns the ID of the running branch.
	BranchID() string
	// StepName returns the name of the currently executing step.
	StepName() string

	// Wait durably parks the current branch until a signal is
	// delivered to topic, or until timeout elapses.
	//
	// # Behavior
	//
	// On the first invocation in a step, Wait registers a wait
	// state against the branch's checkpoint and returns a sentinel
	// error (waitUnwind) that the engine catches at the activity
	// boundary. The activity goroutine exits, the orchestrator
	// persists a checkpoint with BranchState.Wait set, and the
	// execution ends with Status=ExecutionStatusSuspended.
	//
	// When the consumer delivers a signal to the topic via the
	// execution's SignalStore and calls Resume, the engine re-enters
	// the same activity. On the second invocation, Wait sees the
	// delivered payload and returns it to the caller as the first
	// return value.
	//
	// # Replay safety
	//
	// Activities that call Wait MUST be replay-safe: any side
	// effect that runs before the Wait call will run again on the
	// resumed invocation. Use Context.History to memoize expensive
	// or non-idempotent work. The shape is:
	//
	//	func(ctx Context, p Params) (any, error) {
	//	    result, _ := ctx.History().RecordOrReplay("key", func() (any, error) {
	//	        // side-effecting work runs once, replays from cache
	//	    })
	//	    payload, err := ctx.Wait("topic", timeout)
	//	    // post-wait code runs once after the signal arrives
	//	}
	//
	// # Deadline behavior
	//
	// timeout is wall-clock and starts ticking from when Wait is
	// first called; the engine records an absolute deadline at
	// register time. On resume, the engine recomputes the remaining
	// time against the original deadline; a wait that has already
	// expired wakes immediately with ErrWaitTimeout.
	//
	// Routing a timeout to a step (instead of failing the activity)
	// requires a declarative WaitSignalConfig with OnTimeout set;
	// the imperative Context.Wait always surfaces ErrWaitTimeout to
	// the caller.
	//
	// # Custom Context implementations
	//
	// Test doubles or alternative Context implementations MUST
	// forward Wait to the engine's underlying implementation. Wait
	// depends on engine-internal branch state — the checkpoint, the
	// wait registry, the resume path — and a custom Context that
	// returns nil/error from Wait without touching that state will
	// silently break replay semantics. The workflowtest package is
	// the supported pattern for unit tests.
	Wait(topic string, timeout time.Duration) (any, error)
	// History returns the per-activity-invocation persisted cache.
	// Returns a process-local, non-persistent cache if called outside
	// of an activity invocation.
	History() *History
	// ReportProgress forwards a progress update to the configured
	// StepProgressStore, if any. No-op otherwise.
	ReportProgress(detail ProgressDetail)
}

type DefaultChildWorkflowExecutor struct {
	// contains filtered or unexported fields
}

type Each struct {
	Items any    `json:"items"`
	As    string `json:"as,omitempty"`
}

type Edge struct {
	Step      string `json:"step"`
	Condition string `json:"condition,omitempty"`
	// BranchName optionally names the branch created when this edge
	// is followed. Empty means "continue on the current branch".
	BranchName string `json:"branch,omitempty"`
}

type EdgeMatchingStrategy string

type ErrorOutput struct {
	Error   string      `json:"Error"`
	Cause   string      `json:"Cause"`
	Details interface{} `json:"Details,omitempty"`
}

type ExecuteActivityFunc func(ctx Context, parameters map[string]any) (any, error)

type ExecuteOption func(*executeConfig)

type Execution struct {
	// contains filtered or unexported fields
}

type ExecutionCallbacks interface {
	// Workflow-level callbacks
	BeforeWorkflowExecution(ctx context.Context, event *WorkflowExecutionEvent)
	AfterWorkflowExecution(ctx context.Context, event *WorkflowExecutionEvent)

	// Path-level callbacks
	BeforeBranchExecution(ctx context.Context, event *BranchExecutionEvent)
	AfterBranchExecution(ctx context.Context, event *BranchExecutionEvent)

	// Activity-level callbacks
	BeforeActivityExecution(ctx context.Context, event *ActivityExecutionEvent)
	AfterActivityExecution(ctx context.Context, event *ActivityExecutionEvent)
}

type ExecutionContextOptions struct {
	BranchLocalState *BranchLocalState
	Logger           *slog.Logger
	Compiler         script.Compiler
	BranchID         string
	StepName         string
	ExecutionID      string
	SignalStore      SignalStore
	// PendingWait is the wait state the branch was parked on before the
	// current activity invocation, if any. Set by the engine when a
	// checkpoint is being replayed so workflow.Wait can reuse the
	// original deadline.
	PendingWait *WaitState
	// ActivityHistory is the per-activity-invocation persisted cache
	// for this step. Non-nil only when the engine is running an
	// activity; nil for handler contexts that don't execute activity
	// code.
	ActivityHistory *History
}

type ExecutionOption func(*executionConfig)

type ExecutionResult struct {
	// WorkflowName identifies which workflow was executed.
	WorkflowName string

	// Status is the final execution status.
	Status ExecutionStatus

	// Outputs contains the workflow's output values, keyed by output name.
	// Empty if the workflow failed before producing outputs.
	Outputs map[string]any

	// Error is the classified workflow error, if the execution failed.
	// nil when Status is ExecutionStatusCompleted.
	Error *WorkflowError

	// Timing contains execution duration measurements.
	Timing ExecutionTiming

	// FollowUps contains follow-up workflow specs produced by completion hooks.
	// Empty when no hooks are configured or the execution did not complete
	// successfully.
	FollowUps []FollowUpSpec

	// Suspension describes the durable wait(s) that caused the execution
	// to end without completing. Populated when Status is
	// ExecutionStatusSuspended (and in future phases, Paused). nil
	// otherwise.
	Suspension *SuspensionInfo
}

type ExecutionStatus string

type ExecutionSummary struct {
	ExecutionID  string        `json:"execution_id"`
	WorkflowName string        `json:"workflow_name"`
	Status       string        `json:"status"`
	StartTime    time.Time     `json:"start_time"`
	EndTime      time.Time     `json:"end_time,omitempty"`
	Duration     time.Duration `json:"duration"`
	Error        string        `json:"error,omitempty"`
}

type ExecutionTiming struct {
	StartedAt  time.Time
	FinishedAt time.Time
	Duration   time.Duration
}

type FenceFunc func(ctx context.Context) error

type FileActivityLogger struct {
	// contains filtered or unexported fields
}

type FileCheckpointer struct {
	// contains filtered or unexported fields
}

type FollowUpSpec struct {
	// WorkflowName identifies which workflow to trigger.
	WorkflowName string

	// Inputs are the input values for the follow-up workflow.
	Inputs map[string]any

	// Metadata is arbitrary data the consumer can use for routing,
	// deduplication, or prioritization. The library does not inspect it.
	Metadata map[string]any
}

type HeartbeatConfig struct {
	// Interval is how often the heartbeat function is called.
	Interval time.Duration

	// Func is called on each heartbeat tick. Return nil to indicate liveness.
	// Return an error to signal lease loss — the Runner cancels the execution
	// context, causing the workflow to abort.
	Func HeartbeatFunc
}

type HeartbeatFunc func(ctx context.Context) error

type History struct {
	// contains filtered or unexported fields
}

type Input struct {
	Name        string      `json:"name" yaml:"name"`
	Type        string      `json:"type" yaml:"type"`
	Description string      `json:"description,omitempty" yaml:"description,omitempty"`
	Default     interface{} `json:"default,omitempty" yaml:"default,omitempty"`
}

type Inputs struct {
	// contains filtered or unexported fields
}

type JitterStrategy string

type JoinConfig struct {
	// Branches specifies which named branches to wait for. If empty,
	// waits for all active branches.
	Branches []string `json:"branches,omitempty"`

	// Count specifies the number of branches to wait for. If 0, waits
	// for all specified branches.
	Count int `json:"count,omitempty"`

	// BranchMappings specifies where to store branch data. Supports two
	// syntaxes:
	//  1. Store entire branch state: "branchID": "destination"
	//     Example: "branchA": "results.branchA" stores all branchA
	//     variables under results.branchA.
	//  2. Extract specific variables: "branchID.variable": "destination"
	//     Example: "branchA.result": "extracted.value" stores only
	//     branchA.result under extracted.value.
	// Supports nested field extraction using dot notation for both
	// variable names and destinations.
	BranchMappings map[string]string `json:"branch_mappings,omitempty"`
}

type JoinState struct {
	StepName        string      `json:"step_name"`
	WaitingBranchID string      `json:"waiting_branch_id"` // The single branch that's waiting
	Config          *JoinConfig `json:"config"`
	CreatedAt       time.Time   `json:"created_at"`
}

type MemorySignalStore struct {
	// contains filtered or unexported fields
}

type MemoryWorkflowRegistry struct {
	// contains filtered or unexported fields
}

type NullActivityLogger struct{}

type NullCheckpointer struct{}

type Options struct {
	Name        string         `json:"name" yaml:"name"`
	Steps       []*Step        `json:"steps" yaml:"steps"`
	Description string         `json:"description,omitempty" yaml:"description,omitempty"`
	Inputs      []*Input       `json:"inputs,omitempty" yaml:"inputs,omitempty"`
	Outputs     []*Output      `json:"outputs,omitempty" yaml:"outputs,omitempty"`
	State       map[string]any `json:"state,omitempty" yaml:"state,omitempty"`
	// StartAt names the step that the first execution branch begins on.
	// When empty, the first step in Steps is the start step. Validated
	// at New() time to reference an existing step.
	StartAt string `json:"start_at,omitempty" yaml:"start_at,omitempty"`
}

type Output struct {
	Name     string `json:"name" yaml:"name"`
	Variable string `json:"variable" yaml:"variable"`
	// Branch names the execution branch to extract the output value from.
	// Defaults to "main" when empty.
	Branch      string `json:"branch,omitempty" yaml:"branch,omitempty"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

type PauseConfig struct {
	// Reason is an optional human-readable note describing why the
	// step pauses. Stored on BranchState.PauseReason when the pause
	// triggers. The engine does not interpret it.
	Reason string `json:"reason,omitempty"`
}

type ProgressDetail struct {
	// Message is a human-readable description of the current progress.
	Message string

	// Data is arbitrary structured data that consumers can use to
	// drive UIs, metrics, or logging. The library does not inspect
	// it.
	Data map[string]any
}

type RetryConfig struct {
	ErrorEquals    []string       `json:"error_equals,omitempty"`
	MaxRetries     int            `json:"max_retries,omitempty"`
	BaseDelay      time.Duration  `json:"base_delay,omitempty"`
	MaxDelay       time.Duration  `json:"max_delay,omitempty"`
	BackoffRate    float64        `json:"backoff_rate,omitempty"`
	JitterStrategy JitterStrategy `json:"jitter_strategy,omitempty"`
	Timeout        time.Duration  `json:"timeout,omitempty"`
}

type RunOption func(*runConfig)

type Runner struct {
	// contains filtered or unexported fields
}

type RunnerOption func(*runnerConfig)

type Signal struct {
	ExecutionID string
	Topic       string
	Payload     any
}

type SignalStore interface {
	// Send delivers a signal for the given execution + topic. Signals queue
	// in the store even if no branch is currently waiting.
	Send(ctx context.Context, executionID, topic string, payload any) error

	// Receive pops the oldest pending signal for the given execution + topic.
	// Returns (nil, nil) if no signal is pending — callers treat that as
	// "not yet, unwind and wait".
	Receive(ctx context.Context, executionID, topic string) (*Signal, error)
}

type SleepConfig struct {
	// Duration is the wall-clock duration the path should sleep.
	// Must be positive.
	Duration time.Duration `json:"duration"`
}

type Step struct {
	Name                 string               `json:"name"`
	Description          string               `json:"description,omitempty"`
	Store                string               `json:"store,omitempty"`
	Activity             string               `json:"activity,omitempty"`
	Parameters           map[string]any       `json:"parameters,omitempty"`
	Each                 *Each                `json:"each,omitempty"`
	Join                 *JoinConfig          `json:"join,omitempty"`
	WaitSignal           *WaitSignalConfig    `json:"wait_signal,omitempty"`
	Sleep                *SleepConfig         `json:"sleep,omitempty"`
	Pause                *PauseConfig         `json:"pause,omitempty"`
	Next                 []*Edge              `json:"next,omitempty"`
	EdgeMatchingStrategy EdgeMatchingStrategy `json:"edge_matching_strategy,omitempty"`
	Retry                []*RetryConfig       `json:"retry,omitempty"`
	Catch                []*CatchConfig       `json:"catch,omitempty"`
}

type StepProgress struct {
	// StepName identifies the step.
	StepName string

	// BranchID identifies the execution path this step is running on.
	BranchID string

	// Status is the current step status.
	Status StepStatus

	// ActivityName is the activity bound to this step.
	ActivityName string

	// Attempt is the current attempt number (1-based). Increments on retries.
	Attempt int

	// Detail is optional progress information set by activities via
	// Context.ReportProgress. Nil unless the activity reports intra-step
	// progress.
	Detail *ProgressDetail

	// StartedAt is when the step began executing. Zero for pending steps.
	StartedAt time.Time

	// FinishedAt is when the step completed or failed. Zero for running steps.
	FinishedAt time.Time

	// Error is the error message if the step failed. Empty otherwise.
	Error string
}

type StepProgressStore interface {
	UpdateStepProgress(ctx context.Context, executionID string, progress StepProgress) error
}

type StepStatus string

type SuspendedBranch struct {
	BranchID    string
	StepName    string
	Reason      SuspensionReason
	Topic       string    // set for waiting_signal
	WakeAt      time.Time // zero if no deadline
	PauseReason string    // set for paused
}

type SuspensionInfo struct {
	// Reason is the dominant reason for the suspension. When multiple
	// branches are suspended for different reasons, the dominant one is
	// reported; SuspendedBranches has the full breakdown.
	Reason SuspensionReason

	// SuspendedBranches is one entry per hard-suspended branch.
	SuspendedBranches []SuspendedBranch

	// Topics is the union of signal topics any suspended branch is
	// waiting on. Convenience for consumers that just want to know
	// "which channels should deliver into me?".
	Topics []string

	// WakeAt is the earliest absolute deadline across all suspended
	// branches (signal timeouts or sleep wake-ups). Zero if no branch has a
	// deadline.
	WakeAt time.Time
}

type SuspensionReason string

type TypedActivity[TParams, TResult any] interface {

	// Name returns the name of the Activity
	Name() string

	// Execute the Activity with the given parameters.
	Execute(ctx Context, parameters TParams) (TResult, error)
}

type TypedActivityAdapter[TParams, TResult any] struct {
	// contains filtered or unexported fields
}

type ValidationError struct {
	Problems []ValidationProblem
}

type ValidationProblem struct {
	// Step is the name of the step where the problem was found.
	// Empty for workflow-level problems.
	Step string

	// Message describes the problem.
	Message string

	// Err is the sentinel error associated with this problem, if any.
	// Callers can use errors.Is against the enclosing *ValidationError
	// to test for specific problem classes (ErrDuplicateStepName, etc.).
	Err error
}

type WaitKind string

type WaitSignalConfig struct {
	// Topic is a Risor-templated rendezvous key. Required.
	Topic string `json:"topic"`
	// Timeout is the maximum time to wait for the signal. Required.
	Timeout time.Duration `json:"timeout"`
	// Store is the path variable that receives the signal payload when
	// the signal is delivered. Optional.
	Store string `json:"store,omitempty"`
	// OnTimeout is the name of the step to route to when the wait
	// times out. When empty, a timeout fails the step.
	OnTimeout string `json:"on_timeout,omitempty"`
}

type WaitState struct {
	// Kind identifies the wait variant. Required; must be one of the
	// defined WaitKind constants.
	Kind WaitKind `json:"kind"`
	// Topic is the resolved rendezvous topic. Set when Kind == Signal.
	Topic string `json:"topic,omitempty"`
	// WakeAt is the absolute wall-clock deadline at which the wait times
	// out (for signal waits) or wakes (for sleeps). Zero means no
	// deadline; a zero WakeAt with a positive (or explicitly zero)
	// Remaining means the wait clock is frozen by a pause.
	WakeAt time.Time `json:"wake_at,omitzero"`
	// Timeout is the original timeout duration as specified by the caller.
	// Recorded for observability; WakeAt is the authoritative deadline.
	Timeout time.Duration `json:"timeout,omitzero"`
	// Remaining is the amount of time left on the wait when the owning
	// branch was paused mid-wait. Populated for both signal waits and
	// sleeps while the branch is paused; cleared on unpause, at which
	// point WakeAt is recomputed as now + Remaining. The pause clock
	// must not consume the wait's timeout budget (see FR-19 and the
	// freezeWaitOnPause / thawWaitOnUnpause helpers).
	Remaining time.Duration `json:"remaining,omitzero"`
}

type Workflow struct {
	// contains filtered or unexported fields
}

type WorkflowError struct {
	Type    string      `json:"type"`
	Cause   string      `json:"cause"`
	Details interface{} `json:"details,omitempty"`
	Wrapped error       `json:"-"` // Original error being wrapped
}

type WorkflowExecutionEvent struct {
	ExecutionID  string
	WorkflowName string
	Status       ExecutionStatus
	StartTime    time.Time
	EndTime      time.Time
	Duration     time.Duration
	Inputs       map[string]any
	Outputs      map[string]any
	PathCount    int
	Error        error
}

type WorkflowRegistry interface {
	// Register adds a workflow to the registry
	Register(workflow *Workflow) error

	// Get retrieves a workflow by name
	Get(name string) (*Workflow, bool)

	// List returns all registered workflow names
	List() []string
}