Pixir.Workflows (pixir v0.1.5)

Copy Markdown View Source

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.

Summary

Functions

checkpoint_statuses()

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

dry_run(spec, opts \\ [])

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

dry_run_proof_states()

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

partial_proof_states()

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

proof_states()

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

run(parent_session_id, spec, opts \\ [])

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

workflow_statuses()

Top-level Workflow result statuses.

Functions

checkpoint_statuses()

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

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

dry_run(spec, opts \\ [])

@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()

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

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

partial_proof_states()

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

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

proof_states()

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

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

run(parent_session_id, spec, opts \\ [])

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

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

workflow_statuses()

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

Top-level Workflow result statuses.