# `Jido.Runic.Strategy`
[🔗](https://github.com/agentjido/jido_runic/blob/v1.0.0/lib/jido/runic/strategy.ex#L1)

A Jido execution strategy powered by a Runic Workflow DAG.

Incoming signals are converted to Runic Facts and fed into a workflow.
Runnables are emitted as ExecuteRunnable directives for the runtime.
Completed runnables are applied back, advancing the workflow until quiescence.

## Status Lifecycle

    :idle → :running → :waiting → :paused → :success / :failure

- `:idle` — No workflow activity, waiting for input.
- `:running` — Runnables dispatched, awaiting completions.
- `:waiting` — Workflow has pending edges (unsatisfied Join) but
  no dispatchable runnables. Waiting for external signal.
- `:paused` — Step mode: runnables are ready but held until an
  explicit `runic.step` or `runic.resume` signal advances execution.
- `:success` — Workflow quiesced with productions. Terminal.
- `:failure` — All paths exhausted, no productions. Terminal.

## Execution Modes

The strategy supports two execution modes controlled by `execution_mode`:

- `:auto` (default) — Runnables are dispatched automatically as they
  become available. This is the standard fire-and-forget behaviour.
- `:step` — After feeding a signal or applying a result, the strategy
  pauses instead of dispatching. Use `runic.step` to advance one
  generation at a time, or `runic.resume` to switch back to `:auto`.

### Step-Mode Signals

- `"runic.step"` — Dispatches the next batch of held runnables and
  returns to `:paused` (or terminal) once their results are applied.
- `"runic.resume"` — Switches to `:auto` mode and dispatches all
  held runnables, continuing normally.
- `"runic.set_mode"` — Sets `execution_mode` to `:auto` or `:step`.

### Step History

When in `:step` mode, each completed runnable is recorded in
`step_history` with node name, action module, input/output values,
status, and a monotonic timestamp.

## Concurrency Control

`max_concurrent` limits how many runnables are dispatched simultaneously.
Excess runnables are queued and drained via `tick/2`.

---

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