# Workflow Lifecycle Reference

Use this when an agent needs to go from available capabilities to a saved,
validated, runnable deployment.

## Primary Path

1. List sources.
   - CLI: `wf source list`
2. List workflow capabilities.
   - CLI: `wf cap list`
3. Inspect one capability.
   - CLI: `wf cap inspect <name>`
4. Bootstrap a draft workspace.
   - CLI: `wf draft create <workspace_id> --capability <capability>`
5. Inspect/patch/validate the workspace until valid.
   - Use focused CLI commands (`set-name`, `set-route`, `set-input`, `set-output`)
     for common edits.
   - `set-input`, `set-output`, and `set-workflow-output` replace their ordered
     canonical binding lists.
     Repeated sources preserve fan-out to distinct targets. The `--merge`
     variants are compatibility-only and cannot preserve canonical ordering or
     repeated-source fan-out; existing literals are retained for input merges.
   - `set-workflow-output` accepts ordered path/value bindings. Nested
     `input.*` and `state.*` sources can project declared source schemas into
     missing output fields; literals and `context.*` require declared targets.
     `--clear` restores implicit same-name state fallback.
   - Before mapping into a new workflow input, state, or output field, prefer
     `wf draft bind --from ... --to ...` when it should mirror a capability
     local input/output property. It declares the matching schema and merges
     the binding in one revision-checked edit.
   - When adding a new capability-backed step, prefer:

     ```bash
     wf draft add capability ... --description "Step purpose" \
       --input state.value=request.value --value request.format='"json"'
     wf draft update capability ... --retry 0 --clear-timeout
     wf draft validate <workspace_id>
     ```

     Capability updates are presence-aware and preserve capability selection,
     routes, and outputs. Input flags replace the complete canonical input
     list; use `--bindings-file` for lossless path/value interleaving.

     For control flow, use the corresponding typed `wf draft add <kind>`
     command. Use raw `wf draft patch` only when changing structure that no
     focused helper covers.
   - Use JSON Patch only for general structural edits.
6. Save an artifact.
   - Draft artifact:
     `wf draft save <workspace_id> --artifact <artifact_id> --version 1 --title "Workflow Title"`
   - Complete raw plan:
     `wf artifact create-from-plan workflow.plan.json --artifact <artifact_id> --version 1 --title "Workflow Title" --outcome ok`
7. Save and validate a deployment.
   - `wf deploy save <deployment_id> --artifact <artifact_id> --version 1 --binding <logical_source>=<concrete_source>` (or `wf deploy create` alias)
   - `wf deploy validate <deployment_id>`
8. Run the deployment with an optional step budget.
   - CLI: `wf run start <deployment_id> --input-file input.json`
     with `--max-steps 50000` (default `10_000` when omitted; at least 1)
   - Python: `await deployment.run(input, max_steps=50_000)`
   - The budget covers every frame and subgraph scope in the run. Exhaustion
     fails the run; it is never a routable workflow outcome and the denied
     handler never runs.
9. Inspect the run summary first; read bounded traces only when needed.

## Raw Plan Escape Hatch

Draft workspaces are the normal interactive authoring path. If a compiler,
fixture, or advanced client already has a complete raw JSON/YAML workflow plan,
use the CLI escape hatch instead of writing a helper script around the Python
API:

```bash
wf artifact create-from-plan workflow.plan.json \
  --artifact <artifact_id> \
  --version 1 \
  --title "Workflow Title" \
  --outcome ok \
  --binding <logical_source>=<concrete_source>
```

Do not pass draft JSON to `artifact create-from-plan`. Drafts use `steps`,
`routes`, and step field `use`. Raw plans use `nodes`, `edges`, and node field
`node`. See `direct-plan-import.md` for the exact shape.

Then continue with the normal deployment and run steps:

```bash
wf deploy save <deployment_id> --artifact <artifact_id> --version 1
wf deploy validate <deployment_id>
wf run start <deployment_id> --input-file input.json
```

If artifact save returns `suggested_bindings`, include each suggestion as a
deployment binding:

```bash
wf deploy save <deployment_id> \
  --artifact <artifact_id> \
  --version 1 \
  --binding <logical_source>=<concrete_source>
```

If no suggestion is present, do not guess an account-like source binding; inspect
sources and choose the concrete source explicitly.

## Object Model

- **Source**: owner of capabilities, such as `wf.std` or `everything.default`.
- **Workflow capability**: graph-ready `NodeSpec` or saved wrapper artifact.
- **Artifact**: immutable saved workflow or wrapper.
- **Deployment**: mutable binding from artifact version to concrete sources.
- **Run**: durable stopped execution record with status, output, trace count,
  and step budget (`max_steps`, `steps_executed`, `steps_remaining`).

## Result Handling

`wf run start` returns compact status by default. Capture `run_id` even for
completed or failed runs. Inspection exposes the effective budget stored
with the run (`max_steps`, `steps_executed`, `steps_remaining`). Use:

- `wf run inspect <run_id>` for compact stored result.
- `wf run trace <run_id> --from 0 --limit 25` for explicit debug slices.
- `wf run resume <run_id>` only for interrupted runs. Resume reuses the
  persisted budget and accepts no replacement value.

Do not ask for unbounded traces.

## Interrupt Resume Contracts

An interrupted run can carry a self-describing resume contract. Treat
`interrupt.resume_schema` from `wf run inspect` as the source of truth for the
payload you pass to `wf run resume`. Do not read workflow source code just to
guess approval fields when the schema is present.