# Core Concepts

> Applies to: ChengOS v0.1.0+ ｜ Last verified: 2026-08-12 ｜ Source: `crates/cheng-core/src/domain`, `crates/cheng-core/src/types.rs`

Nine terms cover almost everything in ChengOS. They are worth reading once in order, because
each builds on the previous one, and because the documentation and the API use them with
exactly these meanings.

## Workflow

A **workflow** is a directed acyclic graph of nodes and edges. It is the unit you save,
version, run, publish, and export. Workflows are stored in PostgreSQL and identified by a
`WorkflowId` (a UUID).

Every workflow carries a **state**, which is what distinguishes something you are still
building from something other people depend on:

| State | Meaning |
|---|---|
| `draft` | Being built. The default for a new workflow. |
| `active` | Ready to be executed and referenced by other things. |
| `archived` | Retired, kept for reference. |

## Node

A **node** is one step. Each node declares typed inputs and outputs, and is identified by a
component id of the form `category/name` — `io/input_text`, `ai/llm`, `utils/preview`,
`agent/react_agent`. These ids are stable and appear identically in the editor, the API, and
this documentation.

A node's configuration form is not hand-written. The backend emits a JSON Schema with `x-*`
UI extensions, and the editor turns that into controls — see
[node configuration](/docs/editor-node-configuration).

Nodes have **no persistent state of their own**. A node is a pure step from inputs to
outputs; all durable state belongs to the execution that ran it.

## Edge

An **edge** connects one node's output port to another node's input port. Edges do two things
at once: they carry data, and they define execution order. Connections are type-checked in
the editor, so an incompatible pairing is refused at design time rather than failing halfway
through a run.

## Execution

An **execution** is one run of one workflow, with its own `ExecutionId` and its own durable
record. Executions have eight states — more than the usual three, because human review and
timeouts are first-class:

| State | Meaning |
|---|---|
| `pending` | Created, not started |
| `running` | In progress |
| `paused` | Suspended, resumable |
| `waiting_for_review` | Suspended pending a human decision — entered when a tool returns `requires_review: true` |
| `completed` | Finished successfully |
| `failed` | Finished with an error |
| `cancelled` | Stopped by a user |
| `timeout` | Exceeded its time budget |

The last four are **terminal**; the first four are **active**. This distinction matters when
you poll: `/executions/active` returns the active set, and a terminal state will never change
again.

Individual nodes within an execution have their own, simpler lifecycle: `waiting` (for
dependencies) → `ready` → `running` → `completed`, `failed`, or `skipped`.

## Value

Data flowing along edges is a `NodeValue` — a tagged union of string, number, boolean, array,
object, file, and stream. The `file` and `stream` cases are why large payloads and
token-by-token model output work without buffering everything in memory.

## Workspace

A **workspace** is the tenancy and isolation boundary. Workflows, credentials, documents,
tables, knowledge bases, channels, and files all belong to one. Authenticated API requests
name the workspace in the `X-Workspace-Id` header, which is authorized against the caller
rather than merely read.

Each workspace also has a **sandbox**: a directory tree that file and shell tools are confined
to. A node cannot read outside it.

## Credential

A **credential** is an encrypted secret in the vault — an API key, token, password, or OAuth
grant. Nodes reference credentials by id and never contain the secret. Resolution happens
server-side at the moment of use, so secrets never enter a model's prompt context.

## Agent, tool, and skill

An **agent** (`agent/react_agent`) is a node that decides its own steps: it reasons, calls a
tool, observes the result, and repeats until the task is done or a limit stops it. Unlike an
ordinary node, its control flow is not drawn on the canvas.

A **tool** is a capability an agent may invoke — a node exposed to the model, an external MCP
server's tool, or a skill. Tools reach an agent through its `tools` port and through
[Tool Hub](/docs/agent-tools-and-hub).

A **skill** is a packaged, reusable capability with a manifest, instructions, and optional
code, installed into a workspace and discoverable by agents.

## Conversation and channel

A **conversation** is a durable multi-turn dialogue with its own history, independent of any
single execution — one conversation typically spans many executions, one per turn.

A **channel** maps an external application to a workflow. It carries a `channelId` (a
workspace-unique slug identifying *where a message came from*) and a `boundWorkflowId`
(*which workflow runs*). Keeping those two separate is deliberate: the origin of a message
and the choice of what to run are different decisions — see
[the gateway model](/docs/sdk-gateway-model).

## Next steps

- [System overview](/docs/system-overview) — how these map onto running processes.
- [Execution model](/docs/exec-model) — how a graph actually becomes a run.
- [Your first workflow](/docs/quickstart-first-workflow) — see the vocabulary on screen.