API Reference

Current reference map for vyuh_workflow_engine and the CDX workflow integration packages.

Core Runtime

API	Purpose
WorkflowEngine	Runtime orchestrator for loading definitions, starting instances, sending signals, recovery, cancellation, and event streams.
WorkflowBuilder	Fluent builder for code-created executable workflows.
WorkflowDescriptor	Bundle of task, user-task, condition, node processor, and lifecycle hook registrations.
WorkflowStorage	Storage interface and repository set.
Node Results	NodeResult, TaskResult, and user-task completion result shapes.
Workflow Effects	Declarative effects returned by executors and node processors.

Executors

API	Purpose
TaskExecutor	Executes automated service-task work and returns TaskSuccess or TaskFailure.
UserTaskExecutor	Creates human task specs and processes completed user output.
Condition Executors	Evaluates edge and gateway routing conditions.
NodeProcessor	Executes engine-level node behavior for start/end/tasks/gateways/timers/subflows/loops.

Essential Signatures

WorkflowEngine

WorkflowEngine({
  required WorkflowTypeResolver context,
  required WorkflowStorage storage,
  required ExecutionMode executionMode,
  WorkflowEngineConfig config = const WorkflowEngineConfig(),
});

Important methods:

Future<void> initialize();
Future<void> dispose();

void registerWorkflow(Workflow workflow);
Workflow loadWorkflowDefinition(WorkflowDefinition definition);
Workflow loadWorkflowJSON(Map<String, dynamic> json);
Future<Workflow> saveWorkflow(Workflow workflow);
Future<Workflow?> getStoredWorkflow(String code, {int? version});

Future<WorkflowInstance> startWorkflow({
  String? workflowId,
  String? workflowCode,
  int? version,
  Map<String, dynamic> input = const {},
  String? correlationId,
  String? parentInstanceId,
  String? parentNodeId,
  String? userId,
});

Future<void> sendSignal({
  required String workflowInstanceId,
  required String node,
  String? port,
  Map<String, dynamic>? payload,
});

WorkflowBuilder

WorkflowBuilder(String code, String name, {String? description});

WorkflowBuilder start(String id, {String? name});
WorkflowBuilder end(String id, {String? name, String? outcome});
WorkflowBuilder task(
  String id, {
  String? name,
  String? description,
  TaskExecutor? executor,
  TaskExecuteFunction? execute,
  String? storeAs,
  String? schemaType,
});
WorkflowBuilder userTask(
  String id, {
  String? name,
  String? description,
  String? signal,
  UserTaskExecutor? executor,
  UserTaskExecuteFunction? execute,
  String? title,
  String? assignToRole,
  String? assignToUser,
  String? assignToGroup,
  String? schemaType,
  String? priority,
  String? storeAs,
});
WorkflowBuilder signalWait(String id, {required String signal, String? name, String? storeAs});
WorkflowBuilder oneOf(String id, List<Branch> branches, {String? name});
WorkflowBuilder allOf(String id, List<String> targets, {String? name});
WorkflowBuilder anyOf(String id, List<String> targets, {String? name});
Workflow build();

TaskExecutor

abstract class TaskExecutor implements SchemaItem {
  String get schemaType;
  String get name;
  String get description => '';

  Future<TaskResult> execute(ExecutionContext context);
  List<String> validateConfig(Map<String, dynamic> config) => const [];
}

Task results:

sealed class TaskResult {}

class TaskSuccess extends TaskResult {
  const TaskSuccess(List<WorkflowEffect> effects);
}

class TaskFailure extends TaskResult {
  const TaskFailure({
    required ErrorType errorType,
    required String message,
    bool isRetryable = true,
    Map<String, dynamic>? details,
  });
}

UserTaskExecutor

abstract class UserTaskExecutor implements SchemaItem {
  String get schemaType;
  String get name;
  String get description => '';

  Future<WaitForUserTaskResult> execute(ExecutionContext context);

  UserTaskCompletionResult processCompletion(
    Map<String, dynamic> userOutput,
    Map<String, dynamic> taskInput,
    ExecutionContext context,
  );
}

NodeResult

Current high-use node results:

sealed class NodeResult {}

class ContinueResult extends NodeResult { ... }
class SplitContinueResult extends NodeResult { ... }
class WaitForSignalResult extends NodeResult { ... }
class WaitForUserTaskResult extends WaitForSignalResult { ... }
class CompleteWorkflowResult extends NodeResult { ... }
class FailWorkflowResult extends NodeResult { ... }
class WaitForServiceTaskResult extends NodeResult { ... }
class WaitForJoinResult extends NodeResult { ... }
class DropTokenResult extends NodeResult { ... }

See Node Results for the detailed shape.

Data Access

Executors receive ExecutionContext:

final previous = context.get<String>('field');          // previous node output
final initial = context.getInitial<String>('field');    // workflow input
final any = context.getAny<String>('field.path');       // accumulated output
final config = context.getConfig<String>('field');      // node config

Prefer previous-node input for local data flow. Use accumulated output and workflow input deliberately for cross-node or global context.

Storage

abstract class WorkflowStorage {
  WorkflowRepository get workflows;
  WorkflowInstanceRepository get instances;
  UserTaskInstanceRepository get userTaskInstances;
  WorkflowEventRepository get events;

  Future<T> transaction<T>(Future<T> Function() operation);
  Future<void> initialize();
  Future<void> dispose();
  Future<bool> healthCheck();
  Future<StorageStats> getStats();
}

Storage uses WorkflowDefinition for definitions. The engine converts those definitions into executable Workflow objects.

CDX Packages

Package	API surface
cdx_workflow_types	Approval contracts, task actions, activity/status projections.
cdx_workflow_templates	ApprovalTemplate, ApprovalDomain, WorkflowTemplate, canonical approval definition and descriptor.
cdx_feature_workflows	Flutter workflow inbox/status/action/timeline widgets and Vyuh feature/plugin exports.
vyuh_workflow_storage_supabase	SupabaseStorage and SupabaseStorageConfig.
vyuh_workflow_protocol	WorkflowProtocolClient, messages, and transports.
vyuh_workflow_editor	WorkflowEditor, environments, run mode, validation, registry, and editor widgets.

See Also

• CDX Integration
• Loading and Registration
• Storage Adapters
• Glossary