> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows and Run records

> Understand Workflow, Run, Action, and Wait, and select the next operation from the runtime result.

A Workflow defines permitted steps and transitions. A Run saves the input, state, actions, waits, and evidence for one execution. One workflow can have multiple independent Runs.

## Core objects

| Object | Host responsibility |
| - | - |
| Workflow | Define identity, version, entry, steps, and allowed transitions. |
| Run | Retain the same Run ID when resuming. |
| Action | Claim the current action, invoke real host capabilities, and report its result. |
| Wait | Show the proposal and submit the actual decision or required evidence. |
| Store | Save atomically so concurrent results do not overwrite one another. |

Use a new version when changing a definition, and retain definitions referenced by active Runs. Editing prose, state JSON, or a completion label cannot replace a valid transition.

## Define the allowed path

```js theme={null}
import { defineWorkflow, skill, approval, tool } from '@rpamis/comet/runtime';

const workflow = defineWorkflow({
  id: 'report',
  version: '1',
  entry: 'draft',
  steps: {
    draft: skill({ ref: 'draft' }),
    approve: approval({ proposalFrom: 'draft' }),
    publish: tool({ ref: 'publish' }),
  },
  transitions: [
    { from: 'draft', to: 'approve' },
    { from: 'approve', to: 'publish', on: 'approved' },
  ],
});
```

entry identifies initially ready steps. Keys in steps name graph steps; ref names a host handler. transitions declares permitted paths. Several steps may use one handler while retaining separate execution records.

Register workflow with `createRuntime` and start a Run using its fixed id/version. See the [quickstart](/en/sdk/quickstart.md) for a complete runnable example.

## Read progress results

After `runUntilBlocked`, read reason first, then the relevant actions, waits, and business outputs.

| reason | Next operation |
| - | - |
| completed | Inspect business output and the selected path. |
| `approval-required` | Show the current proposal and collect the user's decision. |
| `evidence-required` | Collect and submit the requested evidence. |
| `executor-required` | Register a host executor that supports the action. |
| `action-in-flight` | Query the original executor and wait for its result. |
| `execution-unknown` | Reconcile the original operation before resuming. |
| failed | Inspect the original Action and error, then handle the known failure. |
| `action-limit` | The invocation exhausted its action budget; inspect progress before continuing. |
| cancelled | Stop progression and verify prior operations and stop evidence. |
| idle | Inspect ready steps, join conditions, and child Runs to understand why no action is available. |

inspect reads records without calling models or tools. A business UI should show the current Run, pending Actions/Waits, and the last error so users can choose whether to continue, approve, or reconcile.

## Define steps

Import `defineWorkflow` from `@rpamis/comet/runtime`, or use a definition object as in the quickstart.

| Helper | Work declared |
| - | - |
| skill | Have the host load and execute a Skill. |
| tool | Call a host tool or local business function. |
| approval | Wait for a user decision on the current proposal. |
| evidence | Wait for declared evidence. |
| childWorkflow | Start and link a child workflow. |

Dependencies determine when actions become ready. Parallel steps may finish in different orders, with explicit join conditions. Loops and branches follow declared transitions; handlers cannot jump outside the graph.

## Executors and outcomes

`createRuntimeExecutor` registers named handlers by step ref. `defineRuntimeHandler` parses input before execution, avoiding one large function that dispatches on step names.

Hosts that claim and report independently can use claim, `recordOutcome`, and retry. Retain the original Action identity, attempt, input hash, and claim credentials; report results for that execution.

Successful outputs also pass Schema and business validation. Report known failures as failures. Exceptions after dispatch or interrupted reporting can mean the operation happened; treat them as unknown. See [recovery](/en/sdk/recovery.md).

## User waits

Decisions bind to the Wait ID and current proposal hash. Changed proposals require a new display and confirmation. Old approvals, approvals from another activation, and invented host approvals cannot authorize the current action.

For evidence waits, submit actual evidence; Runtime validates ownership and declared conditions. A finished step, accepted evidence, and a successful external service operation are separate facts and should be shown separately.

## Storage and host responsibilities

`createMemoryRuntimeStore` is suitable for experiments that do not need process recovery. `createFileRuntimeStore` saves Runs in your chosen directory; a new process registers the same definitions and executors to continue.

Runtime does not call models, configure MCP, inject plugin context, or obtain permission for your host. Use [Workflow Application](/en/sdk/applications.md) for pinned Skills, installation entries, protected business files, and distribution.

Continue with [executors](/en/sdk/executors.md), [parallel steps](/en/sdk/parallel.md), [child workflows](/en/sdk/subworkflows.md), and [business state](/en/sdk/state.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.