<?php

declare(strict_types=1);

namespace Drupal\flowdrop_workflow\Service;

use Drupal\flowdrop_workflow\WorkflowDefinitionInterface;

/**
 * Applies a set of mutation primitives to a workflow definition.
 *
 * The single — and only — component that mutates a workflow's stored arrays in
 * the diagnostics flow. It resolves conflicts by precedence (a node removal
 * supersedes any config edit on the same node), cascades node removals to their
 * connected edges, dedupes, and writes through the entity setters. It does NOT
 * save: the {@see WorkflowDoctorInterface} saves after a final re-validate.
 *
 * @api
 */
interface WorkflowMutatorInterface {

  /**
   * Applies the mutations to the workflow in place.
   *
   * @param \Drupal\flowdrop_workflow\WorkflowDefinitionInterface $workflow
   *   The workflow to mutate (written via its setters; not saved).
   * @param list<\Drupal\flowdrop_workflow\Diagnostic\Mutation\WorkflowMutationInterface> $mutations
   *   The mutations to apply, in any order.
   */
  public function apply(WorkflowDefinitionInterface $workflow, array $mutations): void;

}
