<?php

declare(strict_types=1);

namespace Drupal\flowdrop_session\Event;

use Symfony\Contracts\EventDispatcher\Event;

/**
 * Fired when a chat turn starts executing on a session.
 *
 * Part of the documented session turn event contract
 * (docs/reference/api/session-turn-events.md): one turn = one user
 * message = one started + one completed event, correlated by turnId.
 * Fired once the turn's pipeline entity exists, so pipelineId is always
 * set — subscribers that saw a NULL pipelineId in the HTTP TurnResult
 * pick it up here.
 *
 * Fired for every top-level message-driven execution regardless of entry
 * verb (executeTurn, queue worker). Nested sub-workflow invocations on a
 * shared session do not start a turn.
 *
 * Payload evolution is additive-only: fields are never removed or
 * renamed within 1.x.
 *
 * @api
 */
final class SessionTurnStartedEvent extends Event {

  /**
   * The event name.
   */
  public const string NAME = 'flowdrop_session.turn.started';

  /**
   * Constructs a new SessionTurnStartedEvent.
   *
   * @param string $sessionId
   *   The session entity id the turn runs on.
   * @param string $turnId
   *   The turn id — the id of the user message that initiated the turn.
   * @param string $pipelineId
   *   The pipeline entity id executing this turn.
   * @param string $workflowId
   *   The workflow entity id being executed.
   */
  public function __construct(
    public readonly string $sessionId,
    public readonly string $turnId,
    public readonly string $pipelineId,
    public readonly string $workflowId,
  ) {}

}
