execution

type Activity[I, O any] struct {
	// Name must be stable across worker restarts and workflow replay.
	Name string
}

type ActivityCall struct {
	// Name identifies a registered activity.
	Name string
	// Input is passed to the backend codec without a wrapper envelope.
	Input any
	// Options overrides registration defaults according to backend rules.
	Options ActivityOptions
}

type ActivityDefinition struct {
	// Name identifies the activity within its backend registry.
	Name string
	// Options supplies portable registration defaults.
	Options ActivityOptions
	// Handler must be func(context.Context, I) (O, error) or func(context.Context, I) error.
	// Use Activity[I, O].Register for compile-time checking of input and output.
	Handler any
}

type ActivityExecutor interface {
	// ExecuteActivity schedules and waits for a result, decoded into a pointer.
	ExecuteActivity(context.Context, ActivityCall, any) error
	// ExecuteActivityAsync schedules a command in this executor's workflow scope.
	ExecuteActivityAsync(context.Context, ActivityCall) (ActivityFuture, error)
}

type ActivityFuture interface {
	// Get waits using the captured workflow scope and decodes into a pointer.
	Get(context.Context, any) error
	// IsReady reports completion without blocking.
	IsReady() bool
}

type ActivityOptions struct {
	// Queue overrides the activity queue. Empty uses registration or backend defaults.
	Queue string
	// RetryPolicy controls retry behavior for this activity. If zero-valued, the
	// engine uses its default retry policy.
	RetryPolicy RetryPolicy
	// ScheduleToStartTimeout bounds how long the activity may wait in the task
	// queue before a worker starts the attempt. Zero means leave queue-wait
	// unspecified here and let the engine adapter apply its own defaults.
	ScheduleToStartTimeout time.Duration
	// StartToCloseTimeout bounds one activity attempt once a worker has started
	// executing it. Zero means use the engine default.
	StartToCloseTimeout time.Duration
	// HeartbeatTimeout bounds the maximum gap between heartbeats emitted by the
	// running activity. Zero leaves the backend default unchanged.
	HeartbeatTimeout time.Duration
}

type ActivityRegistrar interface {
	// RegisterActivity validates and installs a concrete handler.
	RegisterActivity(context.Context, ActivityDefinition) error
}

type Future[T any] interface {
	// Get blocks until the activity completes and returns the typed result.
	// Once completed, repeated calls return the recorded result.
	Get(ctx context.Context) (T, error)

	// IsReady returns true if the activity has completed (success or failure) and Get()
	// will not block. This allows workflows to poll or implement custom waiting strategies.
	IsReady() bool
}

type RetryPolicy struct {
	// MaxAttempts caps total attempts, including the first. Zero uses backend defaults.
	MaxAttempts int
	// InitialInterval is the delay before the first retry. Zero means use engine default.
	InitialInterval time.Duration
	// BackoffCoefficient multiplies the delay after each retry. Zero uses backend
	// defaults; the backend defines the valid range of explicit coefficients.
	BackoffCoefficient float64
}