@spec async((-> any())) :: {:hourglass_temporal_async, term()}

Spawn an asynchronous workflow scope.

async/1 runs fun.() inline within a child-path scope, swallowing any suspend sentinel so sibling asyncs can also contribute commands. The returned tag is opaque — pass it back to await/1.

The externally observable command_id sequence is governed by child_index_path ++ [child_index].

@spec await({:hourglass_temporal_async, term()}) :: term()

Await the result of an async/1 scope. Returns the value the function returned, or raises / rethrows if the scope failed.

Awaiting a scope whose body suspended (because it issued a command without a resolved result) re-throws the suspend sentinel — so the parent stops cleanly and the activation ships its accumulated commands.

@spec await_all([{:hourglass_temporal_async, term()}]) :: [term()]

Join a list of async/1 scopes, returning their values in order.

Equivalent to mapping await/1 over the list. If any scope has not yet resolved (i.e. it suspended waiting for a command result), await/1 re-throws the suspend sentinel and the activation ships its accumulated commands — correct fan-out behaviour.

@spec await_signal(
  String.t() | atom(),
  keyword()
) :: term() | {:ok, term()} | :timeout

Block (suspend) the workflow until a signal named name has arrived, then return its decoded payload.

Signals are inbound signal_workflow activation jobs. The Nth call to await_signal(name) in a re-execution consumes signals[name][N] (0-based). The call counter resets at the start of every activation (via CommandAccumulator.init/0) so each re-execution of the workflow body deterministically re-consumes the same buffered signals.

When called with timeout: duration, races the signal against a durable timer. Returns {:ok, payload} if the signal arrives first, or :timeout if the timer fires first. The timer command_id is allocated unconditionally every activation to preserve deterministic seq assignment.

Known limitation: if a completion is not acknowledged by the server and the identical activation is redelivered after the signal has already been persisted to state.signals, the signal would be appended a second time (signals lack a seq-based idempotency key). Normal incremental and full-replay paths are correct.

@spec cancelled?() :: boolean()

Returns true if a cancel_workflow activation job has been delivered to this workflow run, false otherwise.

Non-blocking cooperative cancellation: the workflow checks cancelled?/0 at safe points and decides what to do (e.g. skip remaining work and complete gracefully). The flag is set during job ingestion and persists across activations once set — once a cancel arrives it stays true.

@spec continue_as_new(term()) :: no_return()

Terminal: stops the workflow body and emits a ContinueAsNewWorkflowExecution command carrying the serialised input. The Temporal server starts a new run of the same workflow type with fresh history, passing input as the initial argument.

Raises if called outside a workflow evaluator.

@spec info() :: Hourglass.Workflow.Info.t()

Per-activation workflow context.

Returns a %Info{} carrying the workflow's run_id + task_queue. Reads from the evaluator state stamped on the process dict by Hourglass.Workflow.Evaluator.run_body/2. Raises if no evaluator is active on the calling process — info/0 is only meaningful inside a workflow body during evaluation.