# `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 module also exposes non-executing dependency-wave critical-path estimation for
Delegate admission, reusing the same normalization and wave planner as dry-run and
runtime scheduling.

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"`).

Dependents unlock only from `"checkpoint_ready"`, with two explicit carve-outs: an
`apply` step consumes its `apply_from` producer at any status, and a step may name a
subset of its own `depends_on` in `allow_unverified_depends_on` to also admit a
dependency whose child completed successfully but derived `"partial"` — the
shell-less-writer-plus-audit shape. That opt-in is per-step and per-dependency, never
global and never a default, and a step admitted through it records
`verification.unverified_dependencies` and the
`"ran_against_unverified_dependencies"` known limitation in its own checkpoint.

## 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.

# `critical_path`

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

Estimate the dependency-wave critical path without running a Workflow.

# `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*