# FlowDrop Runtime Module

The FlowDrop Runtime module provides a comprehensive execution engine for FlowDrop workflows with support for both synchronous and asynchronous execution modes, real-time monitoring, and advanced orchestration capabilities.

## API Stability

All PHP classes in this module are `@internal` and not part of the public API. They may change without notice in any release. External modules should not extend or type-hint against classes in this namespace.

The stable public API for building custom node processors is in the root `flowdrop` module (`Drupal\flowdrop\Plugin\FlowDropNodeProcessor`, `Drupal\flowdrop\DTO`). See the [BC Policy](../../docs/reference/api/bc-policy.md) for details.

## Features

### Execution Modes

1. **Synchronous Orchestrator** (`synchronous`)
   - Direct execution with immediate results
   - Real-time status updates
   - Interactive workflow execution

2. **Asynchronous Orchestrator** (`asynchronous`)
   - Queue-based background execution
   - Scalable pipeline and job processing
   - Persistent execution state
   - Automatic retry and error handling

### Core Components

- **Node Runtime Service** - Executes individual workflow nodes
- **Execution Context** - Manages execution state and data flow
- **Real-Time Manager** - Provides live status updates and event broadcasting
- **Workflow Compiler** - Optimizes and validates workflow definitions
- **Data Flow Manager** - Handles data transformation between nodes
- **Error Handler** - Comprehensive error management and recovery
- **JSONPath Service** - RFC 9535 compliant data extraction and mapping

## Installation

```bash
drush en flowdrop_runtime
```

## Queue-Based Execution

The asynchronous orchestrator runs a workflow's pipeline in the background via a
single queue:

- **Pipeline Execution Queue** (`flowdrop_runtime_pipeline_execution`) — a queued
  item drives the whole pipeline, executing jobs in dependency order through the
  synchronous pipeline orchestrator, so it shares the same node execution,
  dependency resolution, opt-in retry, and error-port routing as a foreground
  run.

### Queue Processing

```bash
# Process pipeline execution queue
drush queue:run flowdrop_runtime_pipeline_execution
```

## Events

The module dispatches various events during execution:

### Pipeline Events
- `flowdrop.pipeline.created` - Pipeline created
- `flowdrop.pipeline.started` - Pipeline execution started
- `flowdrop.pipeline.completed` - Pipeline completed successfully
- `flowdrop.pipeline.failed` - Pipeline execution failed
- `flowdrop.pipeline.paused` - Pipeline paused
- `flowdrop.pipeline.cancelled` - Pipeline cancelled

### Job Events
- `flowdrop.job.created` - Job created
- `flowdrop.job.started` - Job execution started
- `flowdrop.job.completed` - Job completed successfully
- `flowdrop.job.failed` - Job execution failed

## Dependencies

- `flowdrop` - Core FlowDrop functionality
- `flowdrop_workflow` - Workflow definitions
- `flowdrop_pipeline` - Pipeline entities
- `flowdrop_job` - Job entities
- `flowdrop_node_type` - Node type definitions
