<?php

declare(strict_types=1);

namespace Drupal\flowdrop_runtime\Service\Compiler;

use Drupal\flowdrop_runtime\DTO\Compiler\CompiledWorkflow;
use Drupal\flowdrop_workflow\DTO\WorkflowDTO;

/**
 * Interface for the workflow compiler service.
 *
 * @internal This interface is not part of the public API and may change without notice.
 */
interface WorkflowCompilerInterface {

  /**
   * Compiles a workflow entity into dependency and execution graphs.
   *
   * @param array<string, mixed>|\Drupal\flowdrop_workflow\DTO\WorkflowDTO $workflow
   *   The workflow definition array or WorkflowDTO.
   *
   * @return \Drupal\flowdrop_runtime\DTO\Compiler\CompiledWorkflow
   *   The compiled workflow with both graphs.
   *
   * @throws \Drupal\flowdrop_runtime\Exception\CompilationException
   *   When compilation fails due to validation errors.
   */
  public function compile(array|WorkflowDTO $workflow): CompiledWorkflow;

}
