# `Hephaestus.Core.Instance`
[🔗](https://github.com/hephaestus-org/hephaestus_core/blob/v0.3.1/lib/hephaestus/core/instance.ex#L1)

A runtime instance of a workflow execution.

Tracks the current state of a workflow as it progresses through steps,
including which steps are active (being executed), completed, and the
accumulated context.

## Fields

  * `id` - unique identifier supplied by the caller
  * `workflow` - the workflow module being executed
  * `workflow_version` - the version of the workflow definition (positive integer, default 1)
  * `current_step` - the step module currently being processed (or `nil`)
  * `status` - one of `:pending`, `:running`, `:waiting`, `:completed`, `:failed`
  * `context` - `Hephaestus.Core.Context` with initial data and step results
  * `step_configs` - per-step config overrides keyed by step module
  * `active_steps` - `MapSet` of step modules currently being executed
  * `completed_steps` - `MapSet` of step modules that have finished
  * `runtime_metadata` - dynamic metadata accumulated from step executions
  * `telemetry_metadata` - caller metadata merged into emitted telemetry events
  * `telemetry_start_time` - monotonic start time used to compute telemetry durations
  * `execution_history` - list of `Hephaestus.Core.ExecutionEntry` records

# `status`

```elixir
@type status() :: :pending | :running | :waiting | :completed | :failed
```

The lifecycle status of a workflow instance.

# `t`

```elixir
@type t() :: %Hephaestus.Core.Instance{
  active_steps: MapSet.t(module()),
  completed_steps: MapSet.t(module()),
  context: Hephaestus.Core.Context.t(),
  current_step: module() | nil,
  execution_history: list(),
  id: String.t(),
  runtime_metadata: map(),
  status: status(),
  step_configs: %{optional(module()) => map()},
  telemetry_metadata: map(),
  telemetry_start_time: integer() | nil,
  workflow: module(),
  workflow_version: pos_integer()
}
```

A workflow instance struct tracking execution state, active/completed steps, and context.

# `new`

```elixir
@spec new(module(), pos_integer(), map(), String.t()) :: t()
```

Creates a new workflow instance for the given workflow module and explicit ID.

## Parameters

  * `workflow` - the workflow module to execute
  * `version` - the workflow version (positive integer)
  * `context` - a map of initial data passed to the workflow
  * `id` - explicit identifier for the workflow instance

## Examples

    iex> instance = Instance.new(MyApp.Workflows.OrderFlow, 1, %{order_id: 123}, "orderid::123")
    iex> instance.status
    :pending
    iex> instance.context.initial
    %{order_id: 123}
    iex> instance.workflow_version
    1

---

*Consult [api-reference.md](api-reference.md) for complete listing*