# FlowDrop StateGraph

Stateful graph execution orchestrator with checkpointing, reducers, and human-in-the-loop support.

PHP classes in this module are `@api` or `@internal`. See the [BC Policy](../../docs/reference/api/bc-policy.md) for details.

## Services

### StateManagerInterface

**Service ID:** `flowdrop_stategraph.state_manager`

```php
$manager = \Drupal::service('flowdrop_stategraph.state_manager');

$state = $manager->createInitialState($threadId, $initialData);
$state = $manager->applyUpdate($state, $update, $maxIterations);
$checkpoint = $manager->createCheckpoint($state, $nodeId);
$state = $manager->restoreFromCheckpoint($checkpoint);
$state = $manager->markComplete($state);
$state = $manager->markError($state, $error);
$reducer = $manager->getReducer('append');
```

### CheckpointerInterface

**Service IDs:** `flowdrop_stategraph.memory_checkpointer`, `flowdrop_stategraph.entity_checkpointer`

```php
$checkpointer->put($checkpoint): string;
$checkpointer->get($checkpointId): ?Checkpoint;
$checkpointer->getLatest($threadId): ?Checkpoint;
$checkpointer->list($threadId, $limit): array;
$checkpointer->delete($checkpointId): bool;
$checkpointer->deleteThread($threadId): int;
```

### ApprovalGateInterface

**Service ID:** `flowdrop_stategraph.approval_gate_handler`

```php
$gate->createRequest($nodeId, $checkpoint, $context): string;
$gate->approve($requestId, $userId, $notes): bool;
$gate->reject($requestId, $userId, $reason): bool;
$gate->getStatus($requestId): ApprovalStatus;
$gate->listPending($limit): array;
```

### IteratorHelperInterface

**Service ID:** `flowdrop_stategraph.array_iterator_helper`

```php
$iterator = $helper->initialize($items);
$iterator = $helper->advance($iterator);
$helper->hasMore($iterator): bool;
$helper->getCurrentItem($iterator): mixed;
```

## DTOs

### GraphState

Immutable state container. Fields use `#[StateField]` attribute to declare their reducer strategy:

- `messages` (append) - Conversation history
- `data` (merge) - Workflow data
- `metadata` (merge) - Execution metadata
- `iterator` (replace) - Loop iteration state
- `iterationCount` (replace) - Loop counter
- `threadId` (replace) - Thread identifier

### StateUpdate

```php
$update = StateUpdate::create(['messages' => [$newMessage]]);
$update = $update->withSourceNode($nodeId);
```

### Checkpoint

```php
$checkpoint = Checkpoint::create($state, $nodeId, $parentCheckpointId);
$checkpoint->state: GraphState;
$checkpoint->threadId: string;
$checkpoint->nodeId: string;
```

### ExecutionConfig

```php
ExecutionConfig::forDevelopment($maxIterations);    // Memory checkpointer
ExecutionConfig::forProduction($maxIterations);     // Entity checkpointer
ExecutionConfig::forResume($checkpointId);          // Resume from checkpoint
```

## Reducers

| ID | Behavior |
|----|----------|
| `append` | Appends values to arrays |
| `replace` | Replaces entire value |
| `merge` | Deep merges arrays |

## StateAwareProcessorInterface

Optional interface for node processors that need graph state access:

```php
class MyProcessor extends AbstractFlowDropNodeProcessor
  implements StateAwareProcessorInterface {

  public function setGraphState(GraphState $state): void { ... }
}
```

## Built-in Node Processors

`approval_gate`, `state_storage`, `for_each`, `iterator_start`, `iterator_next`, `iterator_collect`, `loop_control`

## Permissions

| Permission | Description |
|------------|-------------|
| `administer flowdrop_stategraph` | Configure settings and manage checkpoints |
| `create/view/edit/delete state_checkpoint` | Checkpoint entity CRUD (own/any) |
| `manage approval gates` | Approve/reject approval requests |
