Workflows

Space workflows are durable, app/user-scoped automation records that can be authored and inspected through graph nodes. The workflow subsystem owns workflow definitions, topology, runs, run steps, and events; graph maps are interaction contexts over those records, not storage for them.

Runtime and storage scope

App bootstrap creates:

• app.workflow-store
• app.workflow-code-executor
• app.workflow-runner

The default store is rooted at {app.user-data-dir}/workflows/ and is independent of active worlds and graph maps. Definitions persist under workflows/definitions/; runs persist under workflows/runs/. Run context may record a world id, graph map id, or selected graph node keys for provenance, but those values do not determine storage ownership.

Records and keys

Definitions use wf-... ids and contain metadata plus executable step records and canonical workflow edges. Steps use step-... ids and reference a code entity through :code-entity-id; workflow-specific config, schemas, retry settings, and timeouts live on the step. Edges use edge-... ids with :source-step-id, :target-step-id, and optional data/control routing metadata.

Runs use wfr-... ids and record definition id/version, status, input/output, context, current steps, nested run steps, and events. Run steps are addressed by run id plus step id. Events use event-... ids.

Graph-visible workflow keys include:

workflows
workflow-definition:<definition-id>
workflow-step-explorer:<definition-id>
workflow-step:<definition-id>:<step-id>
workflow-run-explorer:<definition-id>
workflow-run:<run-id>
workflow-run-step:<run-id>:<step-id>
workflow-run-timeline:<run-id>
workflow-run-event:<run-id>:<event-id>

Executable step contract

Workflow execution is code-entity-first. Durable workflow steps reference code entities; they do not embed durable source bodies. The code executor evaluates the referenced Fennel code entity with full app/global access and expects a step object with a required :run method plus optional :resume and :cancel methods.

Every execution result must be an outcome table. Valid statuses are :succeeded, :failed, :waiting, :retry, :skipped, and :cancelled. :succeeded and :skipped outcomes may include :next-step-ids to select downstream control-flow targets; omitting it selects all normal downstream continuations. Invalid or unknown outcomes fail the step with structured error data.

Graph doctrine

The graph exposes workflow records through key loaders and node adapters. Graph maps provide user-facing interaction context, visible nodes, and display edges. Workflow definitions remain the canonical owner of workflow topology, so authoring workflow connections mutates the workflow store rather than persisting those derived edges as graph-map topology.

Workflow discovery is explicit and hierarchical:

Workflows root -> selected workflow definition -> selected workflow run -> run details

The Workflows root browse/search surface lists workflow definitions only. Workflow definitions do not auto-expand into steps, runs, run steps, or events. Definition controls open focused explorer nodes, and explorer selections explicitly materialize the selected related nodes in the active graph map. Run steps/events are materialized from explicit run detail controls. This avoids root-level fan-out and keeps graph-map topology limited to records the user has chosen to reveal.

Graph user flow

1. Open Graph.
2. From start, search/select Workflows.
3. Browse/search workflow definitions from the Workflows root, or invoke New Workflow.
4. Open a workflow definition for a compact summary plus Start, New Step, Open Steps, and Open Runs controls.
5. Use Open Steps to browse/search steps or reveal all steps through workflow-step-explorer:<definition-id>.
6. Use Open Runs to browse/search past runs through workflow-run-explorer:<definition-id>; selecting a run materializes only that run node in the active graph map.
7. Use Show Code on a step to open the linked code-entity:<id> node.
8. Edit the Fennel code entity if desired.
9. Use New Step on the definition for additional steps.
10. Connect workflow step nodes; those connections create canonical workflow edges.
11. Click Start / Start Run on the workflow definition to create and reveal a run node in the active graph map.
12. Open the run node, use granular inspection actions such as Open Timeline, Show Run Steps, and Reveal Failed Steps, then inspect long inputs, outputs, errors, logs, or event bodies in payload panels/full node views.

Workflow data remains in WorkflowStore: definitions, steps, edges, runs, run steps, and events are owned there. Fennel source bodies remain in CodeEntityStore. Graph nodes and actions adapt those stores into the current interaction context, and graph maps only provide visibility, selection, and interaction context; they do not own workflow data or code bodies.

Agent sessions

Sidebar agent chats are workflow-backed sessions: one chat is one long-lived workflow run, and each user turn resumes a waiting agent workflow step. The workflow subsystem owns the run, steps, and events; llm.agent.workflow-runner adapts those records to the existing sidebar runner API.

Agent transcript/status/session state is projected from workflow events such as :agent-session-created, :agent-status-changed, and agent item events. Graph workflow nodes expose the same run and event records as the sidebar. See Workflow-backed agent sessions for the event schema and migration command.

V1 exclusions

Version 1 intentionally does not include generic primitive workflow executors for conditions, loops, joins, tool calls, arbitrary agent nodes, or general-purpose human input UI. Sidebar chats use the dedicated workflow-backed agent runner described above; the generic scheduler does not become a provider streaming runtime. V1 also does not sandbox workflow code or store workflow data in graph maps.

• Generic primitive executors for agent/tool/condition/human-input nodes are out of scope.
• Sandboxing workflow code is out of scope.
• Edge-kind, condition, and port editing UI are out of scope.
• Rich node port handles and edge endpoint anchoring are out of scope.
• Naming dialogs, delete confirmations, template galleries, and human-input resume UI are out of scope.
• Moving nodes between graph maps is out of scope.

Validation ladder

For workflow changes, run validation in this order:

1. make fennel-check
2. make constraints
3. Focused workflow tests: store, code executor, runner, and graph
4. Broader relevant suite such as make test for app bootstrap or graph loader registration changes