Skip to main content

Workflow Semantics

This page defines the canonical workflow model for Holon.

Purpose​

Use this page when you need to answer:

  • what a workflow is,
  • what starts a workflow run,
  • what isActive means,
  • how alternate starts work,
  • how time and event semantics are split,
  • what belongs to the workflow versus the host,
  • and how workflows relate to workspace-scoped data.

Current-State Summary​

  • A workflow is the durable workspace-scoped automation artifact.
  • Workflow temporality belongs to the workflow itself, not to a separate top-level scheduler record.
  • isActive gates whether the desktop host may evaluate that workflow's triggers.
  • triggers[] are the canonical workflow-start model.
  • Triggers may target a specific step when the workflow wants to describe an alternate start path itself.
  • Step semantics govern in-run behavior only.
  • Workflow-level start conditions and in-run waiting are separate concepts.
  • Workflows may consume and produce workspace-scoped data or artifacts, but workflows do not define UI.

Relationship Map​

Canonical Definitions​

Workflow​

A workflow is a durable workspace-scoped automation artifact that defines:

  • graph structure,
  • trigger behavior,
  • activation state,
  • step behavior,
  • alternate start behavior when needed,
  • and references to workspace-scoped data or artifacts.

Workflows do not define UI.

Trigger​

A trigger starts a new workflow run.

Triggers belong to the workflow itself. They are not modeled as separate top-level schedule or controller records.

Current canonical trigger families are:

  • Manual: explicit user-initiated start
  • Schedule: time-based or recurring start
  • Event: external or observed event start

Active Workflow​

isActive means the host may evaluate the workflow's triggers.

  • isActive = true: eligible for trigger evaluation
  • isActive = false: persisted and manually runnable, but not background-evaluated

Alternate Start​

A trigger may target a specific step when the workflow wants to describe a non-default start path.

This is a workflow-owned alternate start, not an external scheduler override.

Step​

A step describes behavior inside a run. It does not decide when a workflow exists or becomes active.

Workflow-Level Temporality​

Workflow-level temporality describes when a run should start.

Examples:

  • manual launch
  • recurring schedule
  • polling or watch cadence
  • event-driven start

This belongs to triggers[].

In-Run Waiting​

In-run waiting describes how an already-started run pauses until some condition is satisfied.

Examples:

  • wait for a duration
  • wait until a timestamp
  • wait for an event
  • wait for user or reviewer input

This belongs to workflow steps, not triggers.

Background Workflow​

A background workflow is not a separate artifact kind.

It is an active workflow whose triggers continue to be evaluated while the execution host is alive.

In the current v1 floor, background evaluation is desktop-open only.

Workflow Data Interaction​

Workflows may consume and produce workspace-scoped resources such as:

  • retained artifacts,
  • workflow outputs,
  • observation captures,
  • evidence,
  • and future workflow-scoped data resources.

The workflow owns the automation semantics for using that data. A separate UI system may later interpret and render it.

Core Rules​

  • Workflows own automation semantics.
  • The host owns trigger evaluation infrastructure.
  • Triggers start runs.
  • Wait steps pause runs.
  • isActive gates trigger evaluation, not existence.
  • Alternate starts are workflow-described, not host-invented.
  • Workflows do not define UI.
  • Data interaction may be workflow-owned, but view rendering remains host-owned.

Current Behavior​

  • The frontend workflow contract already carries isActive, triggers[], steps[], connections[], and layout.

  • The desktop host persists workflow-library records and can execute workflow runs on demand.

  • Runtime execution already supports bounded deterministic workflow behavior such as capability execution, frozen-tool execution, AI steps, human gates, timer waits, and explicit event waits.

  • Workflow trigger evaluation and background firing semantics are still being aligned to this model.

  • Default-start runs persist start_node_ids: [] as the explicit canonical representation of "use graph entry nodes".

  • Non-empty start_node_ids are only valid when they correspond to workflow-owned alternate starts declared by trigger metadata such as targetStepId.

  • Runtime execution treats selected alternate starts as synthetic roots for the chosen downstream subgraph, while nodes outside that selected subgraph begin in Skipped.

  • WaitForEvent is distinct from WaitTimer; event waits only resume when an explicit event is delivered.

Limitations And Non-Goals​

  • V1 does not claim OS-level, service-level, or app-closed background execution.
  • V1 background behavior is limited to the desktop host while the app is open.
  • Workflow UI declaration is explicitly out of scope.
  • Trigger evaluation infrastructure must not become a second semantic model that redefines workflow behavior outside the workflow.
  • Event-wait semantics must remain explicit and must not be treated as a disguised timer.