# `Pixir.Workflows`
[🔗](https://github.com/Ranvier-Technologies/pixir/blob/main/lib/pixir/workflows.ex#L1)

Deterministic Workflow orchestration over Pixir Subagents.

A Workflow is a bounded plan of steps with explicit dependency edges and write-set
metadata. Ordinary steps schedule ADR 0011 Subagents; explicit `virtual_overlay`
steps run the internal BEAM-native virtual workspace runner and return `virtual_diff`
evidence without opening a child Session or mutating the parent workspace.

The top-level Workflow result has a narrow terminal contract: `"completed"` means
every step produced a dependent-safe checkpoint, while `"partial"` means at least one
step needs retry, synthesis, inspection, or orchestrator input. Step-level
`checkpoint_status` values carry the detailed truth (`"held"`, `"failed"`,
`"partial"`, `"needs_orchestrator"`, or `"checkpoint_ready"`).

## TODO(delegate-service-v1)

Delegate service mode will eventually need a Workflow strategy, but it should not
bypass this module's checkpoint and partial-outcome vocabulary. Prefer a thin
Delegate adapter that submits a normalized Workflow spec here, then reports
`workflow_id`, child ids, checkpoint readiness, and safe next actions through the same
`delegate status/attach` contract used for Subagent fanout.

# `checkpoint_statuses`

```elixir
@spec checkpoint_statuses() :: [String.t()]
```

Step checkpoint statuses that classify completion, partial evidence, and holds.

# `dry_run`

```elixir
@spec dry_run(
  map(),
  keyword()
) :: {:ok, map()} | {:error, map()}
```

Validate a Workflow and return its normalized execution plan without running it.

# `dry_run_proof_states`

```elixir
@spec dry_run_proof_states() :: [String.t()]
```

Named proof states a Workflow dry-run can prove without spawning Subagents.

# `partial_proof_states`

```elixir
@spec partial_proof_states() :: [String.t()]
```

Named proof states for a Workflow that produced an honest partial outcome.

# `proof_states`

```elixir
@spec proof_states() :: [String.t()]
```

Named proof states used by dry-runs, smoke tasks, and completion audits.

# `run`

```elixir
@spec run(String.t(), map(), keyword()) :: {:ok, map()} | {:error, map()}
```

Run a Workflow by scheduling its steps through `Pixir.Subagents`.

# `workflow_statuses`

```elixir
@spec workflow_statuses() :: [String.t()]
```

Top-level Workflow result statuses.

---

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