<?php

declare(strict_types=1);

namespace Drupal\flowdrop_session\Service;

use Drupal\flowdrop_session\Entity\FlowDropSessionInterface;
use Drupal\flowdrop_session\Entity\FlowDropSessionMessageInterface;
use Drupal\flowdrop_workflow\WorkflowDefinitionInterface;

/**
 * Interface for session message processing.
 *
 * Implementations handle the execution of workflow logic triggered by
 * a user message in a session.
 *
 * @internal
 *   This class is not part of the public API and may change without notice.
 */
interface MessageProcessorInterface {

  /**
   * Processes a session message by executing the associated workflow.
   *
   * Resolves the workflow from the session and delegates to
   * executeWorkflowOnSession().
   *
   * @param \Drupal\flowdrop_session\Entity\FlowDropSessionMessageInterface $message
   *   The message to process.
   *
   * @throws \Exception
   *   If processing fails.
   */
  public function processMessage(FlowDropSessionMessageInterface $message): void;

  /**
   * Executes a workflow on an existing session.
   *
   * Workflow-explicit entry point that bypasses the session→workflow lookup.
   * Used by the sub-workflow path so a sub-pipeline can run inside the
   * parent's session under a different workflow.
   *
   * @param \Drupal\flowdrop_session\Entity\FlowDropSessionMessageInterface $message
   *   The trigger message. Its execution_id is stamped with the new
   *   pipeline id.
   * @param \Drupal\flowdrop_session\Entity\FlowDropSessionInterface $session
   *   The session to run on. The pipeline is stamped with this session_id.
   * @param \Drupal\flowdrop_workflow\WorkflowDefinitionInterface $workflow
   *   The workflow to execute. May differ from $session->getWorkflow().
   * @param bool $nested
   *   TRUE when invoked recursively from a parent workflow's execution on
   *   the same session. Suppresses session-status writes and the
   *   user-facing error bubble — the parent owns those.
   * @param array<string, mixed> $parentContext
   *   Optional execution context inherited from a parent workflow. When
   *   `hierarchy` is present, the new pipeline's playground context
   *   appends the current workflow as the next crumb. Empty for top-level
   *   playground runs.
   *
   * @throws \Exception
   *   If execution fails.
   */
  public function executeWorkflowOnSession(
    FlowDropSessionMessageInterface $message,
    FlowDropSessionInterface $session,
    WorkflowDefinitionInterface $workflow,
    bool $nested = FALSE,
    array $parentContext = [],
  ): void;

}
