# `Runic.Workflow.HookRunner`
[🔗](https://github.com/zblanco/runic/blob/main/lib/workflow/hook_runner.ex#L1)

Runs hooks during the execute phase without requiring workflow access.

This module provides a safe, parallel-friendly way to execute hooks.
Hooks can be either:

1. **New-style (arity-2)**: `fn event, context -> :ok | {:apply, fn} | {:error, term} end`
   - Executed during the execute phase
   - Can return `:ok` or an `apply_fn` for deferred workflow modifications

2. **Legacy (arity-3)**: `fn step, workflow, fact -> workflow end`
   - Converted to apply_fn for backward compatibility
   - NOT executed during execute phase (requires workflow)

## Return Types

Hooks can return:
- `:ok` - Hook completed successfully, no workflow modifications
- `{:apply, apply_fn}` - Hook completed, apply_fn will be called during apply phase
- `{:apply, [apply_fn]}` - Multiple apply functions
- `{:error, reason}` - Hook failed, will cause runnable to fail

# `apply_fn`

```elixir
@type apply_fn() :: (Runic.Workflow.t() -> Runic.Workflow.t())
```

# `hook`

```elixir
@type hook() :: new_hook() | legacy_hook()
```

# `hook_return`

```elixir
@type hook_return() ::
  :ok | {:apply, apply_fn()} | {:apply, [apply_fn()]} | {:error, term()}
```

# `legacy_hook`

```elixir
@type legacy_hook() :: (struct(), Runic.Workflow.t(), Runic.Workflow.Fact.t() ->
                    Runic.Workflow.t())
```

# `new_hook`

```elixir
@type new_hook() :: (Runic.Workflow.HookEvent.t(), Runic.Workflow.CausalContext.t() ->
                 hook_return())
```

# `run_after`

```elixir
@spec run_after(
  Runic.Workflow.CausalContext.t(),
  struct(),
  Runic.Workflow.Fact.t(),
  term()
) ::
  {:ok, [apply_fn()]} | {:error, term()}
```

Runs after hooks with the execution result and collects any apply_fns.

Returns `{:ok, apply_fns}` or `{:error, reason}`.

# `run_before`

```elixir
@spec run_before(Runic.Workflow.CausalContext.t(), struct(), Runic.Workflow.Fact.t()) ::
  {:ok, [apply_fn()]} | {:error, term()}
```

Runs before hooks and collects any apply_fns.

Returns `{:ok, apply_fns}` or `{:error, reason}`.

---

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