<?php

declare(strict_types=1);

namespace Drupal\flowdrop_stategraph\Plugin\FlowDropNodeProcessor;

use Drupal\flowdrop_stategraph\DTO\GraphState;

/**
 * Interface for node processors that work with graph state.
 *
 * Processors implementing this interface receive the current graph state
 * before execution and can return state updates to be applied after.
 *
 * This interface is optional - processors can also access state via the
 * `__state__` key in input parameters. This interface provides a cleaner
 * API for state-heavy processors.
 *
 * Example usage:
 * @code
 * class MyStatefulProcessor extends AbstractFlowDropNodeProcessor
 *     implements StateAwareProcessorInterface {
 *
 *   use StateAwareProcessorTrait;
 *
 *   public function process(ParameterBagInterface $params): array {
 *     // Access state directly (NULL outside StateGraph orchestration).
 *     $messages = $this->getGraphState()?->messages ?? [];
 *
 *     // Process and return state update.
 *     return [
 *       "output" => "result",
 *       "state_update" => [
 *         "messages" => [new Message("assistant", "Response")],
 *       ],
 *     ];
 *   }
 * }
 * @endcode
 *
 * @see \Drupal\flowdrop_stategraph\Plugin\FlowDropNodeProcessor\StateAwareProcessorTrait
 * @see \Drupal\flowdrop_stategraph\DTO\GraphState
 * @see \Drupal\flowdrop_stategraph\DTO\StateUpdate
 *
 * @api
 */
interface StateAwareProcessorInterface {

  /**
   * Sets the current graph state.
   *
   * This method is called by the StateGraph orchestrator before process()
   * is invoked.
   *
   * @param \Drupal\flowdrop_stategraph\DTO\GraphState $state
   *   The current graph state.
   */
  public function setGraphState(GraphState $state): void;

}
