workflow

type ActivityOptions struct {
	// TaskQueue routes the activity to a specific worker pool.
	// Empty means "the workflow's own task queue" (the common case).
	TaskQueue string

	// ScheduleToStartTimeout caps the wait between enqueue and
	// worker pick-up. 0 = unlimited.
	ScheduleToStartTimeout time.Duration

	// StartToCloseTimeout caps a single activity run. Exceeding it
	// forces a retry per RetryPolicy. 0 = unlimited (NOT
	// recommended; configure something reasonable).
	StartToCloseTimeout time.Duration

	// ScheduleToCloseTimeout is the end-to-end budget including
	// retries. 0 means "derive from StartToCloseTimeout *
	// MaximumAttempts".
	ScheduleToCloseTimeout time.Duration

	// HeartbeatTimeout is the max interval between heartbeats for
	// a long-running activity. Exceeding it aborts the attempt
	// and triggers retry. 0 = no heartbeat required.
	HeartbeatTimeout time.Duration

	// RetryPolicy controls attempt count and backoff. nil = the
	// SDK default (unlimited attempts, exponential backoff starting
	// at 1s, capped at 100s). Pass &temporal.RetryPolicy{MaximumAttempts: 1}
	// to disable retries entirely.
	RetryPolicy *temporal.RetryPolicy

	// WaitForCancellation, when true, makes cancellation wait for
	// the activity to acknowledge before returning. Default false:
	// cancellation unblocks the caller immediately and the
	// activity is expected to observe ctx.Done and exit.
	WaitForCancellation bool
}

type CancelFunc func()

type Channel interface {
	ReceiveChannel

	// Send enqueues a value. On an unbuffered channel Send blocks
	// the coroutine until a receiver pairs with it; on a buffered
	// channel it blocks only when the buffer is full.
	Send(ctx Context, val any) error

	// Close marks the channel closed. Further Sends panic;
	// Receives drain any buffered values then report ok=false.
	// Idempotent.
	Close()
}

type ChildWorkflowFuture interface {
	Future

	// GetChildWorkflowExecution returns a Future that settles with
	// the child's WorkflowExecution ({WorkflowID, RunID}). It is
	// settled by the worker as soon as the frontend acknowledges
	// the schedule — typically well before the child's result
	// future settles.
	GetChildWorkflowExecution() Future
}

type Context interface {
	// Deadline returns the time after which the workflow will be
	// canceled, or zero time + false if no deadline is set.
	Deadline() (time.Time, bool)

	// Done returns a channel that is closed when the workflow (or
	// the containing cancel scope) is canceled. Mirrors
	// context.Context.Done.
	Done() <-chan struct{}

	// Err reports why Done was closed. Returns nil while still
	// running, a *temporal.Error once canceled / timed out.
	Err() error

	// Value returns the value associated with key k, or nil.
	Value(k any) any
	// contains filtered or unexported methods
}

type CoroutineEnv interface {
	// Now returns the deterministic workflow clock. It advances
	// only at commit points (timer fire, activity result); it does
	// not track wall-clock time.
	Now() time.Time

	// Logger returns a logger bound to this workflow execution.
	// Writes during replay are suppressed by the worker so logs
	// reflect only the real (non-replayed) progress of the run.
	Logger() log.Logger

	// Sleep blocks the coroutine for d of workflow time, unless the
	// workflow is canceled first. Returns temporal.Canceled if
	// canceled before d elapses.
	Sleep(d time.Duration) error

	// NewTimer schedules a durable timer and returns a Future that
	// settles with nil after d of workflow time, or with
	// temporal.Canceled if the timer is canceled.
	NewTimer(d time.Duration) Future

	// ExecuteActivity submits an activity for execution. The
	// Future settles with the activity's (result, error). The
	// activity handle is opaque to this package: it is resolved
	// against the worker's registered name by the worker itself.
	ExecuteActivity(opts ActivityOptions, activity any, args []any) Future

	// GetSignalChannel returns (a handle to) the named signal
	// channel. Repeated calls with the same name return handles
	// that observe the same queue — signals are keyed by name, not
	// by handle.
	GetSignalChannel(name string) ReceiveChannel

	// NewChannel creates a user channel. buffered=0 makes it
	// unbuffered; >0 is the capacity. name is used only for
	// debugging and replay identity and may be empty.
	NewChannel(name string, buffered int) Channel

	// Select waits for exactly one of the supplied cases to fire
	// and returns its index. The caller fires the matching user
	// callback; this keeps the env purely mechanical.
	//
	// Cases carry either a Future or a ReceiveChannel. The env's
	// implementation is free to reorder "ready" cases according to
	// its own determinism rules, but it must be deterministic
	// across replays.
	Select(cases []SelectCase) int

	// NewCancelScope derives a child cancel scope whose cancel
	// function, when invoked, cancels only workflow primitives
	// created under that scope (timers, activities, selects).
	// Returns a handle opaque to callers and the cancel function.
	NewCancelScope() (scope any, cancel CancelFunc)

	// ExecuteChildWorkflow starts a child workflow and returns a
	// ChildWorkflowFuture. The returned future's Get settles with
	// the child's result; its GetChildWorkflowExecution() returns a
	// Future that settles as soon as the server assigns a runID.
	//
	// Phase-1: the worker forwards the request to the frontend via
	// OpcodeStartChildWorkflow and emits a scheduleChildWorkflow
	// command (kind=3) so history-based replay can recover the
	// linkage. A StubEnv used in tests may fake this path.
	ExecuteChildWorkflow(childWorkflow any, args []any) ChildWorkflowFuture

	// CurrentScope returns the env's current cancel scope, which
	// Context uses to route Done()/Err() calls.
	CurrentScope() any

	// ScopeDone returns a done channel for the supplied scope. It
	// is closed when the scope is canceled.
	ScopeDone(scope any) <-chan struct{}

	// ScopeErr returns the cancellation error for the supplied
	// scope, or nil if not canceled.
	ScopeErr(scope any) error

	// WorkflowInfo returns a snapshot of stable metadata about the
	// running workflow (ID, RunID, TaskQueue, etc.). Phase 1
	// returns zero values for fields the worker hasn't wired yet.
	WorkflowInfo() Info

	// GetVersion returns the recorded version for changeID, clamped to
	// [minSupported, maxSupported]. The first call records
	// maxSupported; subsequent calls (and replays) return the recorded
	// value. See workflow.GetVersion for the user-facing contract.
	GetVersion(changeID string, minSupported, maxSupported Version) Version

	// SideEffect runs fn exactly once per workflow execution and
	// records its result into history. ctx is the user Context for
	// pass-through to fn. The returned bytes are the JSON-encoded
	// result; replays return the recorded bytes without re-running fn.
	SideEffect(fn func(ctx Context) any, ctx Context) ([]byte, error)

	// MutableSideEffect runs fn whenever the workflow re-evaluates
	// changeID. The recorded value is replaced when eq reports the new
	// value differs from the recorded one; otherwise the recorded
	// value is preserved across the call.
	MutableSideEffect(changeID string, fn func(ctx Context) any, eq func(a, b any) bool, ctx Context) ([]byte, error)

	// MetricsHandler returns the workflow-scoped metrics handler, or
	// nil when no provider is wired. workflow.GetMetricsHandler
	// upgrades a nil to a noop so user code never sees nil.
	MetricsHandler() MetricsHandler

	// UpsertSearchAttributes upserts attrs onto the workflow's
	// visibility record. Phase-1 forwards to the frontend; Phase-2
	// will record the upsert into history alongside other commands.
	UpsertSearchAttributes(attrs map[string]any) error
}

type Future interface {
	// Get blocks the workflow coroutine until the future settles,
	// then decodes the result into valPtr. valPtr may be nil, in
	// which case the result payload is dropped. Returns the
	// settlement error, if any.
	Get(ctx Context, valPtr any) error

	// IsReady reports whether the future has settled. Useful for
	// non-blocking peeks inside a Selector callback; most code
	// calls Get directly.
	IsReady() bool

	// ReadyCh returns a channel that is closed once the Future has
	// settled. It is used by the Selector fan-in so a blocking Select
	// can park on a single receive instead of polling. Stable across
	// calls: the same channel is returned every time.
	ReadyCh() <-chan struct{}
}

type Info struct {
	// WorkflowID is the caller-supplied business identifier.
	WorkflowID string

	// RunID is the engine-generated per-execution identifier.
	RunID string

	// WorkflowType is the registered name (typically the Go
	// function name) of the workflow being executed.
	WorkflowType string

	// TaskQueue is the queue the workflow is running on.
	TaskQueue string

	// Namespace groups workflow executions. Defaults to "default".
	Namespace string

	// Attempt is the 1-based retry attempt for this run.
	Attempt int32
}

type LocalActivityOptions struct {
	// ScheduleToCloseTimeout is the end-to-end budget including
	// retries. 0 = derive from StartToCloseTimeout * MaximumAttempts.
	ScheduleToCloseTimeout time.Duration

	// StartToCloseTimeout caps a single attempt. 0 = unlimited.
	StartToCloseTimeout time.Duration

	// RetryPolicy overrides the default retry policy. Nil = SDK
	// default (see temporal.DefaultRetryPolicy).
	RetryPolicy *temporal.RetryPolicy
}

type MetricsCounter interface {
	Inc(delta int64)
}

type MetricsGauge interface {
	Update(value float64)
}

type MetricsHandler interface {
	// WithTags returns a derived handler that emits all metrics with
	// the supplied tags merged in. Tag values must be stable strings;
	// dynamic, per-call values still belong on individual metric calls.
	WithTags(tags map[string]string) MetricsHandler

	// Counter returns an additive metric. Counters never go down.
	Counter(name string) MetricsCounter

	// Gauge returns a sampled metric. The last value wins per tag set.
	Gauge(name string) MetricsGauge

	// Timer returns a timing metric. Record duration with Record.
	Timer(name string) MetricsTimer
}

type MetricsTimer interface {
	Record(d time.Duration)
}

type ReceiveChannel interface {
	// Receive blocks the workflow coroutine until a value is
	// available, decodes it into valPtr, and reports whether the
	// channel is still open via the ok return. If the channel is
	// closed and drained, ok is false and valPtr is untouched.
	Receive(ctx Context, valPtr any) (ok bool)

	// ReceiveAsync is the non-blocking form: it returns false
	// immediately if no value is buffered. Useful inside a
	// Selector callback where you only want to consume if ready.
	ReceiveAsync(valPtr any) (ok bool)

	// Name returns the channel's debug identifier. Empty for
	// unnamed user channels. Signal channels carry the signal name.
	Name() string
	// contains filtered or unexported methods
}

type SelectCase struct {
	Future  Future
	Channel ReceiveChannel
}

type Selector interface {
	AddFuture(f Future, fn func(f Future)) Selector
	AddReceive(ch ReceiveChannel, fn func(ch ReceiveChannel, more bool)) Selector
	AddDefault(fn func()) Selector
	Select(ctx Context)
}

type Settleable interface {
	Future
	// Settle delivers a final (value, err). Subsequent Settle calls
	// are no-ops. value may be nil (e.g. for timers).
	Settle(value []byte, err error)
}

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

type Version int

type WorkflowExecution struct {
	WorkflowID string `json:"workflow_id"`
	RunID      string `json:"run_id,omitempty"`
}