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.
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.
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.
Next steps
- System overview — how these map onto running processes.
- Execution model — how a graph actually becomes a run.
- Your first workflow — see the vocabulary on screen.