<?php

declare(strict_types=1);

namespace Drupal\flowdrop_interrupt\Message;

use Drupal\flowdrop_interrupt\Enum\InterruptType;

/**
 * Contract for an interrupt to be persisted.
 *
 * An InterruptMessage carries everything a node (or other source) wants to
 * say about a new interrupt — type, human-readable message, opaque context.
 * It deliberately holds nothing about *where* in the execution graph the
 * interrupt lives: that identity (workflow_id, node_id, pipeline_id,
 * session_id, job_id) is stamped by the orchestrator via
 * {@see \Drupal\flowdrop_interrupt\DTO\ExecutionStamp} at dispatch time.
 *
 * This is the security boundary that keeps node-controlled data
 * (schema, options, message, context, linked interrupts) separated from
 * authoritative routing/authorization fields the framework owns.
 *
 * Plugins that need additional fields define their own message class
 * extending {@see AbstractInterruptMessage}, pair it with a matching
 * {@see \Drupal\flowdrop_interrupt\Service\InterruptMessageHandlerInterface},
 * and register the handler under the `flowdrop_interrupt.message_handler`
 * service tag. The bus routes by concrete message class — no central
 * dispatch table to edit.
 *
 * @api
 */
interface InterruptMessageInterface {

  /**
   * The interrupt type the persisted entity should carry.
   */
  public function getType(): InterruptType;

  /**
   * The human-readable message displayed alongside this interrupt.
   */
  public function getMessage(): string;

  /**
   * Opaque payload the handler interprets at resolution time.
   *
   * This value is NEVER used as a lookup key by the framework. It is stored
   * on the persisted entity and handed back to the handler verbatim.
   *
   * @return array<string, mixed>
   *   The opaque context payload.
   */
  public function getContext(): array;

}
